<html>
    <head>
    <link rel="stylesheet" href="lmm.css" type="text/css" />
    </head>
<body class="lmm">
<!-- This file is part of the Lisp Machine Manual.  -*-Text-*- -->
<!-- Function Description: Flow of Control -->
<!-- All of the error stuff has been omitted for the time being, since it -->
<!-- is pretty variable.  Fix it up later. -->
<div class='chapter' id='6'>6. Flow of Control</div><p class='cindent'><!-- control structure -->
<p class='cindent'><!-- flow of control -->
	Lisp provides a variety of structures for flow of control.

	Function application is the basic method for construction of
programs.  Operations are written as the application of a function
to its arguments.  Usually, Lisp programs are written as a large collection
of small functions, each of which implements a simple operation.
These functions operate by calling one another, and so larger
operations are defined in terms of smaller ones.

<p class='cindent'><!-- "recursion" -->
	A function may always call itself in Lisp.  The calling of
a function by itself is known as <!-- open: 1, close: 0 --><font class="italic">recursion</font><!-- open: 1, close: 1 --> <!-- MATCHED MATCHED MATCHED -->; it is analogous
to mathematical induction.

<p class='cindent'><!-- "iteration" -->
	The performing of an action repeatedly (usually with some
changes between repetitions) is called <!-- open: 2, close: 1 --><font class="italic">iteration</font><!-- open: 2, close: 2 --> <!-- MATCHED MATCHED MATCHED -->, and is provided
as a basic control structure in most languages.  The <!-- open: 3, close: 2 --><font class="italic">do</font><!-- open: 3, close: 3 --> <!-- MATCHED MATCHED MATCHED --> statement
of PL/I, the <!-- open: 4, close: 3 --><font class="italic">for</font><!-- open: 4, close: 4 --> <!-- MATCHED MATCHED MATCHED --> statement of ALGOL/60, and so on are examples
of iteration primitives.  Lisp provides a general iteration facility
called <!-- open: 5, close: 4 --><font class="lisp">do</font><!-- open: 5, close: 5 --> <!-- MATCHED MATCHED MATCHED -->, which is explained below.

<p class='cindent'><!-- "conditional" -->
	A <!-- open: 6, close: 5 --><font class="italic">conditional</font><!-- open: 6, close: 6 --> <!-- MATCHED MATCHED MATCHED --> construct is one which allows a program
to make a decision, and do one thing or another based on some logical
condition.  Lisp provides <!-- open: 7, close: 6 --><font class="lisp">and</font><!-- open: 7, close: 7 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 8, close: 7 --><font class="lisp">or</font><!-- open: 8, close: 8 --> <!-- MATCHED MATCHED MATCHED -->, which are simple
conditionals, and <!-- open: 9, close: 8 --><font class="lisp">cond</font><!-- open: 9, close: 9 --> <!-- MATCHED MATCHED MATCHED -->, which is a more general conditional.

<p class='cindent'><!-- "non-local exit" -->
<p class='cindent'><!-- "exits" -->
	Non-local exits are similar to the <!-- open: 10, close: 9 --><font class="italic">leave</font><!-- open: 10, close: 10 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 11, close: 10 --><font class="italic">exit</font><!-- open: 11, close: 11 --> <!-- MATCHED MATCHED MATCHED -->, and
<!-- open: 12, close: 11 --><font class="italic">escape</font><!-- open: 12, close: 12 --> <!-- MATCHED MATCHED MATCHED --> constructs in many modern languages.
'c French, Italian, ...
They are similar to
a <!-- open: 13, close: 12 --><font class="italic">return</font><!-- open: 13, close: 13 --> <!-- MATCHED MATCHED MATCHED -->, but are more general.  In Lisp, their scope is
determined at run-time.  They are implemented as the <!-- open: 14, close: 13 --><font class="lisp">catch</font><!-- open: 14, close: 14 --> <!-- MATCHED MATCHED MATCHED --> and
<!-- open: 15, close: 14 --><font class="lisp">*throw</font><!-- open: 15, close: 15 --> <!-- MATCHED MATCHED MATCHED --> functions.

	Lisp Machine Lisp also provides a multiple-process or coroutine capability.
This is explained in the section on <!-- open: 16, close: 15 --><font class="italic">stacks</font><!-- open: 16, close: 16 --> <!-- MATCHED MATCHED MATCHED --> (<a href='fd_sg.html#stack-group'>this link</a>).

<div class='section' id='6.1'>6.1 Conditionals</div>
<div class='defspec' id='and'><font class='exdent'><font class='funcname' id='and'>and</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 17, close: 16 --><font class="lisp">(and <!-- open: 18, close: 16 --><font class="italic">form1 form2</font><!-- open: 18, close: 17 --> ... )</font><!-- open: 18, close: 18 --> <!-- MATCHED MATCHED MATCHED --> evaluates the <!-- open: 19, close: 18 --><font class="italic">form</font><!-- open: 19, close: 19 --> <!-- MATCHED MATCHED MATCHED -->s one at a time,
from left to right.  If any <!-- open: 20, close: 19 --><font class="italic">form</font><!-- open: 20, close: 20 --> <!-- MATCHED MATCHED MATCHED --> evaluates to <!-- open: 21, close: 20 --><font class="lisp">nil</font><!-- open: 21, close: 21 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 22, close: 21 --><font class="lisp">and</font><!-- open: 22, close: 22 --> <!-- MATCHED MATCHED MATCHED -->
immediately returns <!-- open: 23, close: 22 --><font class="lisp">nil</font><!-- open: 23, close: 23 --> <!-- MATCHED MATCHED MATCHED --> without evaluating the remaining
<!-- open: 24, close: 23 --><font class="italic">forms</font><!-- open: 24, close: 24 --> <!-- MATCHED MATCHED MATCHED -->.  If all the <!-- open: 25, close: 24 --><font class="italic">forms</font><!-- open: 25, close: 25 --> <!-- MATCHED MATCHED MATCHED --> evaluate non-<!-- open: 26, close: 25 --><font class="lisp">nil</font><!-- open: 26, close: 26 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 27, close: 26 --><font class="lisp">and</font><!-- open: 27, close: 27 --> <!-- MATCHED MATCHED MATCHED --> returns
the value of the last <!-- open: 28, close: 27 --><font class="italic">form</font><!-- open: 28, close: 28 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 29, close: 28 --><font class="lisp">and</font><!-- open: 29, close: 29 --> <!-- MATCHED MATCHED MATCHED --> can be used both for logical operations,
where <!-- open: 30, close: 29 --><font class="lisp">nil</font><!-- open: 30, close: 30 --> <!-- MATCHED MATCHED MATCHED --> stands for <!-- open: 31, close: 30 --><font class="italic">False</font><!-- open: 31, close: 31 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 32, close: 31 --><font class="lisp">t</font><!-- open: 32, close: 32 --> <!-- MATCHED MATCHED MATCHED --> stands for <!-- open: 33, close: 32 --><font class="italic">True</font><!-- open: 33, close: 33 --> <!-- MATCHED MATCHED MATCHED -->, and as a
conditional expression. 
<pre class='lisp'>
<font class='exdent'>Examples:
</font><!-- exdent -->(and x y)

(and (setq temp (assq x y))
     (rplacd temp z))

(and (not error-p)
     (princ "There was no error."))
</pre>
Note: <!-- open: 34, close: 33 --><font class="lisp">(and) =&gt; t</font><!-- open: 34, close: 34 --> <!-- MATCHED MATCHED MATCHED -->, which is the identity for this operation.
</div>

<div class='defspec' id='or'><font class='exdent'><font class='funcname' id='or'>or</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 35, close: 34 --><font class="lisp">(or <!-- open: 36, close: 34 --><font class="italic">form1 form2</font><!-- open: 36, close: 35 --> ...)</font><!-- open: 36, close: 36 --> <!-- MATCHED MATCHED MATCHED --> evaluates the <!-- open: 37, close: 36 --><font class="italic">form</font><!-- open: 37, close: 37 --> <!-- MATCHED MATCHED MATCHED -->s one by one from left to right.
If a <!-- open: 38, close: 37 --><font class="italic">form</font><!-- open: 38, close: 38 --> <!-- MATCHED MATCHED MATCHED --> evaluates to <!-- open: 39, close: 38 --><font class="lisp">nil</font><!-- open: 39, close: 39 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 40, close: 39 --><font class="lisp">or</font><!-- open: 40, close: 40 --> <!-- MATCHED MATCHED MATCHED --> proceeds to evaluate the
next <!-- open: 41, close: 40 --><font class="italic">form</font><!-- open: 41, close: 41 --> <!-- MATCHED MATCHED MATCHED -->.  If there are no more <!-- open: 42, close: 41 --><font class="italic">form</font><!-- open: 42, close: 42 --> <!-- MATCHED MATCHED MATCHED -->s, <!-- open: 43, close: 42 --><font class="lisp">or</font><!-- open: 43, close: 43 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 44, close: 43 --><font class="lisp">nil</font><!-- open: 44, close: 44 --> <!-- MATCHED MATCHED MATCHED -->.
But if a <!-- open: 45, close: 44 --><font class="italic">form</font><!-- open: 45, close: 45 --> <!-- MATCHED MATCHED MATCHED --> evaluates non-<!-- open: 46, close: 45 --><font class="lisp">nil</font><!-- open: 46, close: 46 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 47, close: 46 --><font class="lisp">or</font><!-- open: 47, close: 47 --> <!-- MATCHED MATCHED MATCHED --> immediately returns
that value without evaluating any remaining <!-- open: 48, close: 47 --><font class="italic">form</font><!-- open: 48, close: 48 --> <!-- MATCHED MATCHED MATCHED -->s.  <!-- open: 49, close: 48 --><font class="lisp">or</font><!-- open: 49, close: 49 --> <!-- MATCHED MATCHED MATCHED --> can
be used both for logical operations, where <!-- open: 50, close: 49 --><font class="lisp">nil</font><!-- open: 50, close: 50 --> <!-- MATCHED MATCHED MATCHED --> stands for False
and <!-- open: 51, close: 50 --><font class="lisp">t</font><!-- open: 51, close: 51 --> <!-- MATCHED MATCHED MATCHED --> for True, and as a conditional expression.

Note:  <!-- open: 52, close: 51 --><font class="lisp">(or) =&gt; nil</font><!-- open: 52, close: 52 --> <!-- MATCHED MATCHED MATCHED -->, the identity for this operation.
</div>

<div class='defspec' id='cond'><font class='exdent'><font class='funcname' id='cond'>cond</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->The <!-- open: 53, close: 52 --><font class="lisp">cond</font><!-- open: 53, close: 53 --> <!-- MATCHED MATCHED MATCHED --> special form consists of the symbol <!-- open: 54, close: 53 --><font class="lisp">cond</font><!-- open: 54, close: 54 --> <!-- MATCHED MATCHED MATCHED --> followed by
several <!-- open: 55, close: 54 --><font class="italic">clauses</font><!-- open: 55, close: 55 --> <!-- MATCHED MATCHED MATCHED -->.  Each clause consists of a <!-- open: 56, close: 55 --><font class="italic">predicate</font><!-- open: 56, close: 56 --> <!-- MATCHED MATCHED MATCHED --> followed
by zero or more <!-- open: 57, close: 56 --><font class="italic">forms</font><!-- open: 57, close: 57 --> <!-- MATCHED MATCHED MATCHED -->.  Sometimes the predicate is called the
<!-- open: 58, close: 57 --><font class="italic">antecedent</font><!-- open: 58, close: 58 --> <!-- MATCHED MATCHED MATCHED --> and the forms are called the <!-- open: 59, close: 58 --><font class="italic">consequents</font><!-- open: 59, close: 59 --> <!-- MATCHED MATCHED MATCHED -->. 

<pre class='lisp'>
(cond (<!-- open: 60, close: 59 --><font class="italic">antecedent consequent consequent</font><!-- open: 60, close: 60 --> <!-- MATCHED MATCHED MATCHED -->...)
      (<!-- open: 61, close: 60 --><font class="italic">antecedent</font><!-- open: 61, close: 61 --> <!-- MATCHED MATCHED MATCHED -->)
      (<!-- open: 62, close: 61 --><font class="italic">antecedent consequent</font><!-- open: 62, close: 62 --> <!-- MATCHED MATCHED MATCHED --> ...)
      ... )
</pre>

The idea is that each clause represents a case which
is selected if its antecedent is satisfied and the antecedents
of all preceding clauses were not satisfied.  When a clause
is selected, its consequent forms are evaluated.

<!-- open: 63, close: 62 --><font class="lisp">cond</font><!-- open: 63, close: 63 --> <!-- MATCHED MATCHED MATCHED --> processes its clauses in order from left to right.  First,
the antecedent of the current clause is evaluated.  If the result is
<!-- open: 64, close: 63 --><font class="lisp">nil</font><!-- open: 64, close: 64 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 65, close: 64 --><font class="lisp">cond</font><!-- open: 65, close: 65 --> <!-- MATCHED MATCHED MATCHED --> advances to the next clause.  Otherwise, the cdr of
the clause is treated as a list of forms, or consequents, which are
evaluated in order from left to right.  After evaluating the
consequents, <!-- open: 66, close: 65 --><font class="lisp">cond</font><!-- open: 66, close: 66 --> <!-- MATCHED MATCHED MATCHED --> returns without inspecting any remaining
clauses.  The value of the <!-- open: 67, close: 66 --><font class="lisp">cond</font><!-- open: 67, close: 67 --> <!-- MATCHED MATCHED MATCHED --> special form is the value of the
last consequent evaluated, or the value of the antecedent if there
were no consequents in the clause.  If <!-- open: 68, close: 67 --><font class="lisp">cond</font><!-- open: 68, close: 68 --> <!-- MATCHED MATCHED MATCHED --> runs out of clauses,
that is, if every antecedent is <!-- open: 69, close: 68 --><font class="lisp">nil</font><!-- open: 69, close: 69 --> <!-- MATCHED MATCHED MATCHED -->, that is, if no case is
selected, the value of the <!-- open: 70, close: 69 --><font class="lisp">cond</font><!-- open: 70, close: 70 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 71, close: 70 --><font class="lisp">nil</font><!-- open: 71, close: 71 --> <!-- MATCHED MATCHED MATCHED -->. 
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->    (cond ((zerop x)    ;<!-- open: 72, close: 71 --><font class="main">First clause:</font><!-- open: 72, close: 72 --> <!-- MATCHED MATCHED MATCHED -->
           (+ y 3))     ; (zerop x)<!-- open: 73, close: 72 --><font class="main"> is the antecedent.</font><!-- open: 73, close: 73 --> <!-- MATCHED MATCHED MATCHED -->
                        ; (+ y 3)<!-- open: 74, close: 73 --><font class="main"> is the consequent.</font><!-- open: 74, close: 74 --> <!-- MATCHED MATCHED MATCHED -->
          ((null y)     ;<!-- open: 75, close: 74 --><font class="main">A clause with 2 consequents:</font><!-- open: 75, close: 75 --> <!-- MATCHED MATCHED MATCHED -->
           (setq y 4)   ;<!-- open: 76, close: 75 --><font class="main"> this</font><!-- open: 76, close: 76 --> <!-- MATCHED MATCHED MATCHED -->
           (cons x z))  ;<!-- open: 77, close: 76 --><font class="main"> and this.</font><!-- open: 77, close: 77 --> <!-- MATCHED MATCHED MATCHED -->
          (z)           ;<!-- open: 78, close: 77 --><font class="main">A clause with no consequents:</font><!-- open: 78, close: 78 --> <!-- MATCHED MATCHED MATCHED -->
			;<!-- open: 79, close: 78 --><font class="main"> the antecedent is just z.</font><!-- open: 79, close: 79 --> <!-- MATCHED MATCHED MATCHED -->
	  (t		;<!-- open: 80, close: 79 --><font class="main">An antecedent of </font><!-- open: 80, close: 80 --> <!-- MATCHED MATCHED MATCHED -->t
	   105)		;<!-- open: 81, close: 80 --><font class="main"> is always satisfied.</font><!-- open: 81, close: 81 --> <!-- MATCHED MATCHED MATCHED -->
       )		;<!-- open: 82, close: 81 --><font class="main">This is the end of the cond.</font><!-- open: 82, close: 82 --> <!-- MATCHED MATCHED MATCHED -->
</pre>
</div>

<div class='defmac' id='if'><font class='exdent'><font class='funcname' id='if'>if</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --><!-- open: 83, close: 82 --><font class="lisp">if</font><!-- open: 83, close: 83 --> <!-- MATCHED MATCHED MATCHED --> allows a simple "if-then-else" conditional to
be expressed as <!-- open: 84, close: 83 --><font class="lisp">(if <!-- open: 85, close: 83 --><font class="italic">pred-form</font><!-- open: 85, close: 84 --> <!-- open: 86, close: 84 --><font class="italic">then-form</font><!-- open: 86, close: 85 --> <!-- open: 87, close: 85 --><font class="italic">else-form</font><!-- open: 87, close: 86 -->)</font><!-- open: 87, close: 87 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 88, close: 87 --><font class="lisp">if</font><!-- open: 88, close: 88 --> <!-- MATCHED MATCHED MATCHED --> is provided for stylistic reasons; some people think
it looks nicer than <!-- open: 89, close: 88 --><font class="lisp">cond</font><!-- open: 89, close: 89 --> <!-- MATCHED MATCHED MATCHED --> for the simple case it handles.
<!-- open: 90, close: 89 --><font class="lisp">(if <!-- open: 91, close: 89 --><font class="italic">x y z</font><!-- open: 91, close: 90 -->)</font><!-- open: 91, close: 91 --> <!-- MATCHED MATCHED MATCHED --> expands into <!-- open: 92, close: 91 --><font class="lisp">(cond (<!-- open: 93, close: 91 --><font class="italic">x</font><!-- open: 93, close: 92 --> <!-- open: 94, close: 92 --><font class="italic">y</font><!-- open: 94, close: 93 -->) (t <!-- open: 95, close: 93 --><font class="italic">z</font><!-- open: 95, close: 94 -->))</font><!-- open: 95, close: 95 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defmac' id='selectq'><font class='exdent'><font class='funcname' id='selectq'>selectq</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->Many programs require <!-- open: 96, close: 95 --><font class="lisp">cond</font><!-- open: 96, close: 96 --> <!-- MATCHED MATCHED MATCHED --> forms which check various
specific values of a form.
<pre class='lisp'>
<!-- open: 97, close: 96 --><font class="main">A typical example:</font><!-- open: 97, close: 97 --> <!-- MATCHED MATCHED MATCHED -->
(cond ((eq x 'foo) ...)
      ((eq x 'bar) ...)
      ((memq x '(baz quux mum)) ...)
      (t ...))
</pre>
The <!-- open: 98, close: 97 --><font class="lisp">selectq</font><!-- open: 98, close: 98 --> <!-- MATCHED MATCHED MATCHED --> macro can be used for such tests.  
Its form is as follows:
<pre class='lisp'>
(selectq <!-- open: 99, close: 98 --><font class="italic">key-form</font><!-- open: 99, close: 99 --> <!-- MATCHED MATCHED MATCHED -->
	 (<!-- open: 100, close: 99 --><font class="italic">pattern consequent consequent</font><!-- open: 100, close: 100 --> <!-- MATCHED MATCHED MATCHED --> ...)
	 (<!-- open: 101, close: 100 --><font class="italic">pattern consequent consequent</font><!-- open: 101, close: 101 --> <!-- MATCHED MATCHED MATCHED --> ...)
	 (<!-- open: 102, close: 101 --><font class="italic">pattern consequent consequent</font><!-- open: 102, close: 102 --> <!-- MATCHED MATCHED MATCHED --> ...)
	 ...)
</pre>
Its first "argument" is a form, which is evaluated (only once) as the
first thing <!-- open: 103, close: 102 --><font class="lisp">selectq</font><!-- open: 103, close: 103 --> <!-- MATCHED MATCHED MATCHED --> does.  The resulting value is called the <!-- open: 104, close: 103 --><font class="italic">key</font><!-- open: 104, close: 104 --> <!-- MATCHED MATCHED MATCHED -->.  It is
followed by any number of <!-- open: 105, close: 104 --><font class="italic">clauses</font><!-- open: 105, close: 105 --> <!-- MATCHED MATCHED MATCHED -->.  The <!-- open: 106, close: 105 --><font class="lisp">car</font><!-- open: 106, close: 106 --> <!-- MATCHED MATCHED MATCHED --> of each clause is
compared with the key, and if it matches, the consequents of this
clause are evaluated, and <!-- open: 107, close: 106 --><font class="lisp">selectq</font><!-- open: 107, close: 107 --> <!-- MATCHED MATCHED MATCHED --> returns the value of the last
consequent.  If there are no matches, <!-- open: 108, close: 107 --><font class="lisp">selectq</font><!-- open: 108, close: 108 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 109, close: 108 --><font class="lisp">nil</font><!-- open: 109, close: 109 --> <!-- MATCHED MATCHED MATCHED -->.
Note that the patterns are <!-- open: 110, close: 109 --><font class="italic">not</font><!-- open: 110, close: 110 --> <!-- MATCHED MATCHED MATCHED --> evaluated; if you want them to
be evaluated use <!-- open: 111, close: 110 --><font class="lisp">select</font><!-- open: 111, close: 111 --> <!-- MATCHED MATCHED MATCHED --> rather than <!-- open: 112, close: 111 --><font class="lisp">selectq</font><!-- open: 112, close: 112 --> <!-- MATCHED MATCHED MATCHED -->.
	A <!-- open: 113, close: 112 --><font class="italic">pattern</font><!-- open: 113, close: 113 --> <!-- MATCHED MATCHED MATCHED --> may be any of:
<table>
<tr valign='top'>
<td><font class='lisp'> 1) A symbol</font></td><td>If the <!-- open: 114, close: 113 --><font class="italic">key</font><!-- open: 114, close: 114 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 115, close: 114 --><font class="lisp">eq</font><!-- open: 115, close: 115 --> <!-- MATCHED MATCHED MATCHED --> to the symbol, it matches.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> 2) A number</font></td><td>If the <!-- open: 116, close: 115 --><font class="italic">key</font><!-- open: 116, close: 116 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 117, close: 116 --><font class="lisp">eq</font><!-- open: 117, close: 117 --> <!-- MATCHED MATCHED MATCHED --> to the number, it matches.
Only small numbers (<!-- open: 118, close: 117 --><font class="italic">fixnums</font><!-- open: 118, close: 118 --> <!-- MATCHED MATCHED MATCHED -->) will work.
</td></tr>
<tr valign='top'>
<td><font class='lisp'> 3) A list</font></td><td>If the <!-- open: 119, close: 118 --><font class="italic">key</font><!-- open: 119, close: 119 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 120, close: 119 --><font class="lisp">eq</font><!-- open: 120, close: 120 --> <!-- MATCHED MATCHED MATCHED --> to one of the elements of the list,
then it matches.  The elements of the list should be symbols
or fixnums.
</td></tr>
<tr valign='top'><td colspan='2'><font class='lisp'> 4) <!-- open: 121, close: 120 --><font class="lisp">t</font><!-- open: 121, close: 121 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 122, close: 121 --><font class="lisp">otherwise</font><!-- open: 122, close: 122 --> <!-- MATCHED MATCHED MATCHED --></font></td><td><!-- empty --></td></tr>
<tr><td><!-- empty title --></td><td>The symbols <!-- open: 123, close: 122 --><font class="lisp">t</font><!-- open: 123, close: 123 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 124, close: 123 --><font class="lisp">otherwise</font><!-- open: 124, close: 124 --> <!-- MATCHED MATCHED MATCHED --> are special keywords which match anything.  
Either symbol may be used, it makes no difference.
<!-- open: 125, close: 124 --><font class="lisp">t</font><!-- open: 125, close: 125 --> <!-- MATCHED MATCHED MATCHED --> is accepted for compatibility with Maclisp's <!-- open: 126, close: 125 --><font class="lisp">caseq</font><!-- open: 126, close: 126 --> <!-- MATCHED MATCHED MATCHED --> construct.
</td></tr><!-- item_ --></table><!-- end table -->

<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(selectq x		;<!-- open: 127, close: 126 --><font class="main">This is the same as the <!-- open: 128, close: 126 --><font class="lisp">cond</font><!-- open: 128, close: 127 --> example</font><!-- open: 128, close: 128 --> <!-- MATCHED MATCHED MATCHED -->
	 (foo ...)	;<!-- open: 129, close: 128 --><font class="main"> above.</font><!-- open: 129, close: 129 --> <!-- MATCHED MATCHED MATCHED -->
	 (bar ...)
	 ((baz quux mum) ...)
	 (otherwise ...))
</pre>
</div>

<div class='defmac' id='select'><font class='exdent'><font class='funcname' id='select'>select</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --><!-- open: 130, close: 129 --><font class="lisp">select</font><!-- open: 130, close: 130 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 131, close: 130 --><font class="lisp">selectq</font><!-- open: 131, close: 131 --> <!-- MATCHED MATCHED MATCHED -->, except that the elements of the
patterns are evaluated before they are used.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(select (frob x)
   (foo 1)
   ((bar baz) 2)
   (otherwise 3))
<!-- open: 132, close: 131 --><font class="main">is equivalent to</font><!-- open: 132, close: 132 --> <!-- MATCHED MATCHED MATCHED -->
(let ((var (frob x)))
  (cond ((eq var foo) 1)
	((or (eq var bar) (eq var baz)) 2)
	(t 3)))
</pre>
</div>

<div class='defmac' id='selector'><font class='exdent'><font class='funcname' id='selector'>selector</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --><!-- open: 133, close: 132 --><font class="lisp">selector</font><!-- open: 133, close: 133 --> <!-- MATCHED MATCHED MATCHED --> is the same as <!-- open: 134, close: 133 --><font class="lisp">select</font><!-- open: 134, close: 134 --> <!-- MATCHED MATCHED MATCHED -->, except that you get to specify the function
used for the comparison instead of <!-- open: 135, close: 134 --><font class="lisp">eq</font><!-- open: 135, close: 135 --> <!-- MATCHED MATCHED MATCHED -->.  For example,
<pre class='lisp'>
(selector (frob x) equal
   (('(one . two)) (frob-one x))
   (('(three . four)) (frob-three x))
   (otherwise (frob-any x)))
</pre>
</div>

<div class='defmac' id='dispatch'><font class='exdent'><font class='funcname' id='dispatch'>dispatch</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --><!-- open: 136, close: 135 --><font class="lisp">(dispatch <!-- open: 137, close: 135 --><font class="italic">byte-specifier</font><!-- open: 137, close: 136 --> <!-- open: 138, close: 136 --><font class="italic">n</font><!-- open: 138, close: 137 --> <!-- open: 139, close: 137 --><font class="italic">clauses...</font><!-- open: 139, close: 138 -->)</font><!-- open: 139, close: 139 --> <!-- MATCHED MATCHED MATCHED --> is the same
as <!-- open: 140, close: 139 --><font class="lisp">select</font><!-- open: 140, close: 140 --> <!-- MATCHED MATCHED MATCHED --> (not <!-- open: 141, close: 140 --><font class="lisp">selectq</font><!-- open: 141, close: 141 --> <!-- MATCHED MATCHED MATCHED -->), but the key is obtained by evaluating
<!-- open: 142, close: 141 --><font class="lisp">(ldb <!-- open: 143, close: 141 --><font class="italic">byte-specifier n</font><!-- open: 143, close: 142 -->)</font><!-- open: 143, close: 143 --> <!-- MATCHED MATCHED MATCHED -->.
'findex "ldb"
<!-- open: 144, close: 143 --><font class="italic">byte-specifier</font><!-- open: 144, close: 144 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 145, close: 144 --><font class="italic">n</font><!-- open: 145, close: 145 --> <!-- MATCHED MATCHED MATCHED --> are both evaluated.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(princ (dispatch 0202 cat-type
	   (0 "Siamese.")
	   (1 "Persian.")
	   (2 "Alley.")
	   (3 (ferror nil
		      "~S is not a known cat type."
		      cat-type))))
</pre>
<!-- This example borrowed from DuMouchel.CatData -->
It is not necessary to include all possible values of the byte which
will be dispatched on.
[This function may get flushed.]
</div>

<div class='section' id='6.2'>6.2 Iteration</div><p class='cindent'><!-- "iteration" -->
<div class='defspec' id='prog'><font class='exdent'><font class='funcname' id='prog'>prog</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 146, close: 145 --><font class="lisp">prog</font><!-- open: 146, close: 146 --> <!-- MATCHED MATCHED MATCHED --> is a special form which provides temporary variables,
sequential evaluation of forms, and a "goto" facility.  A typical <!-- open: 147, close: 146 --><font class="lisp">prog</font><!-- open: 147, close: 147 --> <!-- MATCHED MATCHED MATCHED -->
looks like:
<pre class='lisp'>
(prog (<!-- open: 148, close: 147 --><font class="italic">var1 var2</font><!-- open: 148, close: 148 --> <!-- MATCHED MATCHED MATCHED --> (<!-- open: 149, close: 148 --><font class="italic">var3 init3</font><!-- open: 149, close: 149 --> <!-- MATCHED MATCHED MATCHED -->) <!-- open: 150, close: 149 --><font class="italic">var4</font><!-- open: 150, close: 150 --> <!-- MATCHED MATCHED MATCHED --> (<!-- open: 151, close: 150 --><font class="italic">var5 init5</font><!-- open: 151, close: 151 --> <!-- MATCHED MATCHED MATCHED -->))
 <!-- open: 152, close: 151 --><font class="italic">tag1</font><!-- open: 152, close: 152 --> <!-- MATCHED MATCHED MATCHED -->
     <!-- open: 153, close: 152 --><font class="italic">statement1</font><!-- open: 153, close: 153 --> <!-- MATCHED MATCHED MATCHED -->
     <!-- open: 154, close: 153 --><font class="italic">statement2</font><!-- open: 154, close: 154 --> <!-- MATCHED MATCHED MATCHED -->
 <!-- open: 155, close: 154 --><font class="italic">tag2</font><!-- open: 155, close: 155 --> <!-- MATCHED MATCHED MATCHED -->
     <!-- open: 156, close: 155 --><font class="italic">statement2</font><!-- open: 156, close: 156 --> <!-- MATCHED MATCHED MATCHED -->
     . . .
    )
</pre>
<!-- open: 157, close: 156 --><font class="italic">var1, var2, ...</font><!-- open: 157, close: 157 --> <!-- MATCHED MATCHED MATCHED --> are temporary variables.  When the <!-- open: 158, close: 157 --><font class="lisp">prog</font><!-- open: 158, close: 158 --> <!-- MATCHED MATCHED MATCHED --> is entered, the
values of these variables are saved.  When the <!-- open: 159, close: 158 --><font class="lisp">prog</font><!-- open: 159, close: 159 --> <!-- MATCHED MATCHED MATCHED --> is finished,
the saved values are restored.  The initial value of a variable inside
the <!-- open: 160, close: 159 --><font class="lisp">prog</font><!-- open: 160, close: 160 --> <!-- MATCHED MATCHED MATCHED --> depends on whether the variable had an associated <!-- open: 161, close: 160 --><font class="italic">init</font><!-- open: 161, close: 161 --> <!-- MATCHED MATCHED MATCHED -->
form or not; if it did, then the <!-- open: 162, close: 161 --><font class="italic">init</font><!-- open: 162, close: 162 --> <!-- MATCHED MATCHED MATCHED --> form is evaluated and becomes
the initial value of the corresponding variable.  If there was no <!-- open: 163, close: 162 --><font class="italic">init</font><!-- open: 163, close: 163 --> <!-- MATCHED MATCHED MATCHED --> form,
the variable is initialized to <!-- open: 164, close: 163 --><font class="lisp">nil</font><!-- open: 164, close: 164 --> <!-- MATCHED MATCHED MATCHED -->.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(prog ((a t)  b  (c 5)  (d (car '(zz . pp))))
      <!-- open: 165, close: 164 --><font class="italic">&lt;body&gt;</font><!-- open: 165, close: 165 --> <!-- MATCHED MATCHED MATCHED -->
      )
</pre>
The initial value of <!-- open: 166, close: 165 --><font class="lisp">a</font><!-- open: 166, close: 166 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 167, close: 166 --><font class="lisp">t</font><!-- open: 167, close: 167 --> <!-- MATCHED MATCHED MATCHED -->, that of <!-- open: 168, close: 167 --><font class="lisp">b</font><!-- open: 168, close: 168 --> <!-- MATCHED MATCHED MATCHED --> is <!-- open: 169, close: 168 --><font class="lisp">nil</font><!-- open: 169, close: 169 --> <!-- MATCHED MATCHED MATCHED -->, that of <!-- open: 170, close: 169 --><font class="lisp">c</font><!-- open: 170, close: 170 --> <!-- MATCHED MATCHED MATCHED --> is
the fixnum 5, and that of <!-- open: 171, close: 170 --><font class="lisp">d</font><!-- open: 171, close: 171 --> <!-- MATCHED MATCHED MATCHED --> is the symbol <!-- open: 172, close: 171 --><font class="lisp">zz</font><!-- open: 172, close: 172 --> <!-- MATCHED MATCHED MATCHED -->.
The binding and initialization of the variables is done in
<!-- open: 173, close: 172 --><font class="italic">parallel</font><!-- open: 173, close: 173 --> <!-- MATCHED MATCHED MATCHED -->; that is,
all the initial values are computed before any of the variables are changed.

	The part of a <!-- open: 174, close: 173 --><font class="lisp">prog</font><!-- open: 174, close: 174 --> <!-- MATCHED MATCHED MATCHED --> after the variable list is called the <!-- open: 175, close: 174 --><font class="italic">body</font><!-- open: 175, close: 175 --> <!-- MATCHED MATCHED MATCHED -->.
An item in the body may be a symbol or a number, in which case it is called a
<!-- open: 176, close: 175 --><font class="italic">tag</font><!-- open: 176, close: 176 --> <!-- MATCHED MATCHED MATCHED -->, or some other form (i.e. a list), in which case it is called a 
<!-- open: 177, close: 176 --><font class="italic">statement</font><!-- open: 177, close: 177 --> <!-- MATCHED MATCHED MATCHED -->.

	After <!-- open: 178, close: 177 --><font class="lisp">prog</font><!-- open: 178, close: 178 --> <!-- MATCHED MATCHED MATCHED --> binds the temporary variables, it processes each form
in its body sequentially.  <!-- open: 179, close: 178 --><font class="italic">tags</font><!-- open: 179, close: 179 --> <!-- MATCHED MATCHED MATCHED --> are skipped over.  <!-- open: 180, close: 179 --><font class="italic">Statements</font><!-- open: 180, close: 180 --> <!-- MATCHED MATCHED MATCHED -->
are evaluated, and their returned values discarded.  If the end of the body
is reached, the <!-- open: 181, close: 180 --><font class="lisp">prog</font><!-- open: 181, close: 181 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 182, close: 181 --><font class="lisp">nil</font><!-- open: 182, close: 182 --> <!-- MATCHED MATCHED MATCHED -->.  However, two special forms
may be used in <!-- open: 183, close: 182 --><font class="lisp">prog</font><!-- open: 183, close: 183 --> <!-- MATCHED MATCHED MATCHED --> bodies to alter the flow of control.
If <!-- open: 184, close: 183 --><font class="lisp">(return <!-- open: 185, close: 183 --><font class="italic">x</font><!-- open: 185, close: 184 -->)</font><!-- open: 185, close: 185 --> <!-- MATCHED MATCHED MATCHED --> is evaluated,
<!-- open: 186, close: 185 --><font class="lisp">prog</font><!-- open: 186, close: 186 --> <!-- MATCHED MATCHED MATCHED --> stops processing its body, evaluates <!-- open: 187, close: 186 --><font class="italic">x</font><!-- open: 187, close: 187 --> <!-- MATCHED MATCHED MATCHED -->, and returns the result.
If <!-- open: 188, close: 187 --><font class="lisp">(go <!-- open: 189, close: 187 --><font class="italic">tag</font><!-- open: 189, close: 188 -->)</font><!-- open: 189, close: 189 --> <!-- MATCHED MATCHED MATCHED --> is evaluated, <!-- open: 190, close: 189 --><font class="lisp">prog</font><!-- open: 190, close: 190 --> <!-- MATCHED MATCHED MATCHED --> jumps to the part of the body
labelled with the <!-- open: 191, close: 190 --><font class="italic">tag</font><!-- open: 191, close: 191 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 192, close: 191 --><font class="italic">tag</font><!-- open: 192, close: 192 --> <!-- MATCHED MATCHED MATCHED --> is not evaluated.
The "computed-<!-- open: 193, close: 192 --><font class="lisp">go</font><!-- open: 193, close: 193 --> <!-- MATCHED MATCHED MATCHED -->" (mis)feature of Maclisp is not supported.

	The compiler requires that <!-- open: 194, close: 193 --><font class="lisp">go</font><!-- open: 194, close: 194 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 195, close: 194 --><font class="lisp">return</font><!-- open: 195, close: 195 --> <!-- MATCHED MATCHED MATCHED --> forms be
<!-- open: 196, close: 195 --><font class="italic">lexically</font><!-- open: 196, close: 196 --> <!-- MATCHED MATCHED MATCHED --> within the scope of the <!-- open: 197, close: 196 --><font class="lisp">prog</font><!-- open: 197, close: 197 --> <!-- MATCHED MATCHED MATCHED -->; it is not possible for
one function to <!-- open: 198, close: 197 --><font class="lisp">return</font><!-- open: 198, close: 198 --> <!-- MATCHED MATCHED MATCHED --> to a <!-- open: 199, close: 198 --><font class="lisp">prog</font><!-- open: 199, close: 199 --> <!-- MATCHED MATCHED MATCHED --> which is in progress in its
caller.  This restriction happens not to be enforced in the interpreter.
Thus, a program which contains a <!-- open: 200, close: 199 --><font class="lisp">go</font><!-- open: 200, close: 200 --> <!-- MATCHED MATCHED MATCHED --> which is not
contained within the body of a <!-- open: 201, close: 200 --><font class="lisp">prog</font><!-- open: 201, close: 201 --> <!-- MATCHED MATCHED MATCHED --> (or a <!-- open: 202, close: 201 --><font class="lisp">do</font><!-- open: 202, close: 202 --> <!-- MATCHED MATCHED MATCHED -->, see below)
cannot be compiled.  Since virtually all programs will be compiled
at some time, the restriction should be adhered to.

	Sometimes code which is lexically within more than one <!-- open: 203, close: 202 --><font class="lisp">prog</font><!-- open: 203, close: 203 --> <!-- MATCHED MATCHED MATCHED -->
(or <!-- open: 204, close: 203 --><font class="lisp">do</font><!-- open: 204, close: 204 --> <!-- MATCHED MATCHED MATCHED -->) form wants to <!-- open: 205, close: 204 --><font class="lisp">return</font><!-- open: 205, close: 205 --> <!-- MATCHED MATCHED MATCHED --> from one of the outer <!-- open: 206, close: 205 --><font class="lisp">prog</font><!-- open: 206, close: 206 --> <!-- MATCHED MATCHED MATCHED -->s.
However, the <!-- open: 207, close: 206 --><font class="lisp">return</font><!-- open: 207, close: 207 --> <!-- MATCHED MATCHED MATCHED --> function normally returns from the innermost 
<!-- open: 208, close: 207 --><font class="lisp">prog</font><!-- open: 208, close: 208 --> <!-- MATCHED MATCHED MATCHED -->.  In order to make <!-- open: 209, close: 208 --><font class="lisp">return</font><!-- open: 209, close: 209 --> <!-- MATCHED MATCHED MATCHED -->ing from outer <!-- open: 210, close: 209 --><font class="lisp">prog</font><!-- open: 210, close: 210 --> <!-- MATCHED MATCHED MATCHED -->s more
convenient, a <!-- open: 211, close: 210 --><font class="lisp">prog</font><!-- open: 211, close: 211 --> <!-- MATCHED MATCHED MATCHED --> may be given a <!-- open: 212, close: 211 --><font class="italic">name</font><!-- open: 212, close: 212 --> <!-- MATCHED MATCHED MATCHED --> by which it may be
referenced by a function called <!-- open: 213, close: 212 --><font class="lisp">return-from</font><!-- open: 213, close: 213 --> <!-- MATCHED MATCHED MATCHED -->, which is similar to
<!-- open: 214, close: 213 --><font class="lisp">return</font><!-- open: 214, close: 214 --> <!-- MATCHED MATCHED MATCHED --> but allows a particular <!-- open: 215, close: 214 --><font class="lisp">prog</font><!-- open: 215, close: 215 --> <!-- MATCHED MATCHED MATCHED --> to be specified.
If the first subform of a <!-- open: 216, close: 215 --><font class="lisp">prog</font><!-- open: 216, close: 216 --> <!-- MATCHED MATCHED MATCHED --> is a non-<!-- open: 217, close: 216 --><font class="lisp">nil</font><!-- open: 217, close: 217 --> <!-- MATCHED MATCHED MATCHED --> symbol
(rather than a variable list), it is the name of the <!-- open: 218, close: 217 --><font class="lisp">prog</font><!-- open: 218, close: 218 --> <!-- MATCHED MATCHED MATCHED -->.
See the description of the <!-- open: 219, close: 218 --><font class="lisp">return-from</font><!-- open: 219, close: 219 --> <!-- MATCHED MATCHED MATCHED --> special form,
on <font color='red'>LINK:(</font>return-from-fun).
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(prog george (a b d)
      (prog (c b)
            ...
            (return-from george (cons b d))
            ...))
</pre>

	If the symbol <!-- open: 220, close: 219 --><font class="lisp">t</font><!-- open: 220, close: 220 --> <!-- MATCHED MATCHED MATCHED --> is used as the name
of a <!-- open: 221, close: 220 --><font class="lisp">prog</font><!-- open: 221, close: 221 --> <!-- MATCHED MATCHED MATCHED -->, then it will be made "invisible" to <!-- open: 222, close: 221 --><font class="lisp">return</font><!-- open: 222, close: 222 --> <!-- MATCHED MATCHED MATCHED -->s;
<!-- open: 223, close: 222 --><font class="lisp">return</font><!-- open: 223, close: 223 --> <!-- MATCHED MATCHED MATCHED -->s inside that <!-- open: 224, close: 223 --><font class="lisp">prog</font><!-- open: 224, close: 224 --> <!-- MATCHED MATCHED MATCHED --> will return to the next outermost level
whose name is not <!-- open: 225, close: 224 --><font class="lisp">t</font><!-- open: 225, close: 225 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 226, close: 225 --><font class="lisp">(return-from t ...)</font><!-- open: 226, close: 226 --> <!-- MATCHED MATCHED MATCHED --> will return
from a <!-- open: 227, close: 226 --><font class="lisp">prog</font><!-- open: 227, close: 227 --> <!-- MATCHED MATCHED MATCHED --> named <!-- open: 228, close: 227 --><font class="lisp">t</font><!-- open: 228, close: 228 --> <!-- MATCHED MATCHED MATCHED -->.

See also the <!-- open: 229, close: 228 --><font class="lisp">do</font><!-- open: 229, close: 229 --> <!-- MATCHED MATCHED MATCHED --> special form, which uses a body similar to
<!-- open: 230, close: 229 --><font class="lisp">prog</font><!-- open: 230, close: 230 --> <!-- MATCHED MATCHED MATCHED -->. The <!-- open: 231, close: 230 --><font class="lisp">do</font><!-- open: 231, close: 231 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 232, close: 231 --><font class="lisp">*catch</font><!-- open: 232, close: 232 --> <!-- MATCHED MATCHED MATCHED -->, and <!-- open: 233, close: 232 --><font class="lisp">*throw</font><!-- open: 233, close: 233 --> <!-- MATCHED MATCHED MATCHED --> special forms are
included in Lisp Machine Lisp as an attempt to encourage goto-less programming
style, which often leads to more readable, more easily maintained code.  The
programmer is recommended to use these functions instead of <!-- open: 234, close: 233 --><font class="lisp">prog</font><!-- open: 234, close: 234 --> <!-- MATCHED MATCHED MATCHED -->
wherever reasonable. 
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(prog (x y z)  ;x, y, z<!-- open: 235, close: 234 --><font class="main"> are prog variables  - temporaries.</font><!-- open: 235, close: 235 --> <!-- MATCHED MATCHED MATCHED -->
   (setq y (car w) z (cdr w))     ;w<!-- open: 236, close: 235 --><font class="main"> is a free variable.</font><!-- open: 236, close: 236 --> <!-- MATCHED MATCHED MATCHED -->
loop
   (cond ((null y) (return x))
         ((null z) (go err)))
rejoin
   (setq x (cons (cons (car y) (car z))
                 x))
   (setq y (cdr y)
         z (cdr z))
   (go loop)
err
   (break are-you-sure? t)
   (setq z y)
   (go rejoin))
</pre>
</div>

<div class='defspec' id='prog*'><font class='exdent'><font class='funcname' id='prog*'>prog*</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->The <!-- open: 237, close: 236 --><font class="lisp">prog*</font><!-- open: 237, close: 237 --> <!-- MATCHED MATCHED MATCHED --> special form is almost the same as <!-- open: 238, close: 237 --><font class="lisp">prog</font><!-- open: 238, close: 238 --> <!-- MATCHED MATCHED MATCHED -->.  The only
difference is that the binding and initialization of the temporary
variables is done <!-- open: 239, close: 238 --><font class="italic">sequentially</font><!-- open: 239, close: 239 --> <!-- MATCHED MATCHED MATCHED -->, so each one can depend on the
previous ones.  For example,
<pre class='lisp'>
(prog ((y z) (x y)) (return x))
</pre>
returns the value of <!-- open: 240, close: 239 --><font class="lisp">z</font><!-- open: 240, close: 240 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defspec' id='do'><font class='exdent'><font class='funcname' id='do'>do</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->The <!-- open: 241, close: 240 --><font class="lisp">do</font><!-- open: 241, close: 241 --> <!-- MATCHED MATCHED MATCHED --> special form provides a generalized iteration facility,
with an arbitrary number of "index variables" whose values are saved
when the <!-- open: 242, close: 241 --><font class="lisp">do</font><!-- open: 242, close: 242 --> <!-- MATCHED MATCHED MATCHED --> is entered and restored when it is left, i.e. they are
bound by the <!-- open: 243, close: 242 --><font class="lisp">do</font><!-- open: 243, close: 243 --> <!-- MATCHED MATCHED MATCHED -->.  The index variables are used in the iteration
performed by <!-- open: 244, close: 243 --><font class="lisp">do</font><!-- open: 244, close: 244 --> <!-- MATCHED MATCHED MATCHED -->.  At the beginning, they are initialized to
specified values, and then at the end of each trip around the loop the
values of the index variables are changed according to specified
rules.  <!-- open: 245, close: 244 --><font class="lisp">do</font><!-- open: 245, close: 245 --> <!-- MATCHED MATCHED MATCHED --> allows the programmer to specify a predicate which
determines when the iteration will terminate.  The value to be
returned as the result of the form may, optionally, be specified. 

<!-- open: 246, close: 245 --><font class="lisp">do</font><!-- open: 246, close: 246 --> <!-- MATCHED MATCHED MATCHED --> comes in two varieties.

The newer variety of
<!-- open: 247, close: 246 --><font class="lisp">do</font><!-- open: 247, close: 247 --> <!-- MATCHED MATCHED MATCHED --> looks like:
<pre class='lisp'>
(do ((<!-- open: 248, close: 247 --><font class="italic">var init repeat</font><!-- open: 248, close: 248 --> <!-- MATCHED MATCHED MATCHED -->)...)
    (<!-- open: 249, close: 248 --><font class="italic">end-test exit-form</font><!-- open: 249, close: 249 --> <!-- MATCHED MATCHED MATCHED -->...)
    <!-- open: 250, close: 249 --><font class="italic">body</font><!-- open: 250, close: 250 --> <!-- MATCHED MATCHED MATCHED -->...)
</pre>

The first item in the form is a list of zero or more index variable
specifiers.  Each index variable specifier is a list of the name of a
variable <!-- open: 251, close: 250 --><font class="italic">var</font><!-- open: 251, close: 251 --> <!-- MATCHED MATCHED MATCHED -->, an initial value <!-- open: 252, close: 251 --><font class="italic">init</font><!-- open: 252, close: 252 --> <!-- MATCHED MATCHED MATCHED -->, which defaults to <!-- open: 253, close: 252 --><font class="lisp">nil</font><!-- open: 253, close: 253 --> <!-- MATCHED MATCHED MATCHED -->
if it is omitted, and a repeat value <!-- open: 254, close: 253 --><font class="italic">repeat</font><!-- open: 254, close: 254 --> <!-- MATCHED MATCHED MATCHED -->.  If <!-- open: 255, close: 254 --><font class="italic">repeat</font><!-- open: 255, close: 255 --> <!-- MATCHED MATCHED MATCHED --> is
omitted, the <!-- open: 256, close: 255 --><font class="italic">var</font><!-- open: 256, close: 256 --> <!-- MATCHED MATCHED MATCHED --> is not changed between repetitions.

In index variable specifier can also be just the name of a variable.
In this case, the variable has an initial value of <!-- open: 257, close: 256 --><font class="lisp">nil</font><!-- open: 257, close: 257 --> <!-- MATCHED MATCHED MATCHED -->, and is
not changed between repetitions.

All assignment to the index variables is done in parallel.  At the
beginning of the first iteration, all the <!-- open: 258, close: 257 --><font class="italic">init</font><!-- open: 258, close: 258 --> <!-- MATCHED MATCHED MATCHED -->s are evaluated,
then the <!-- open: 259, close: 258 --><font class="italic">var</font><!-- open: 259, close: 259 --> <!-- MATCHED MATCHED MATCHED -->s are saved, then the <!-- open: 260, close: 259 --><font class="italic">var</font><!-- open: 260, close: 260 --> <!-- MATCHED MATCHED MATCHED -->s are <!-- open: 261, close: 260 --><font class="italic">set</font><!-- open: 261, close: 261 --> <!-- MATCHED MATCHED MATCHED --> to the
values of the <!-- open: 262, close: 261 --><font class="italic">init</font><!-- open: 262, close: 262 --> <!-- MATCHED MATCHED MATCHED -->s.  To put it another way, the <!-- open: 263, close: 262 --><font class="italic">var</font><!-- open: 263, close: 263 --> <!-- MATCHED MATCHED MATCHED -->s are
<!-- open: 264, close: 263 --><font class="lisp">lambda</font><!-- open: 264, close: 264 --> <!-- MATCHED MATCHED MATCHED -->-bound to the values of the <!-- open: 265, close: 264 --><font class="italic">init</font><!-- open: 265, close: 265 --> <!-- MATCHED MATCHED MATCHED -->s.  Note that the
<!-- open: 266, close: 265 --><font class="italic">init</font><!-- open: 266, close: 266 --> <!-- MATCHED MATCHED MATCHED -->s are evaluated <!-- open: 267, close: 266 --><font class="italic">before</font><!-- open: 267, close: 267 --> <!-- MATCHED MATCHED MATCHED --> the <!-- open: 268, close: 267 --><font class="italic">var</font><!-- open: 268, close: 268 --> <!-- MATCHED MATCHED MATCHED -->s are bound, i.e.
lexically <!-- open: 269, close: 268 --><font class="italic">outside</font><!-- open: 269, close: 269 --> <!-- MATCHED MATCHED MATCHED --> of the <!-- open: 270, close: 269 --><font class="lisp">do</font><!-- open: 270, close: 270 --> <!-- MATCHED MATCHED MATCHED -->.
At the beginning of each succeeding iteration those <!-- open: 271, close: 270 --><font class="italic">var</font><!-- open: 271, close: 271 --> <!-- MATCHED MATCHED MATCHED -->s that have
<!-- open: 272, close: 271 --><font class="italic">repeat</font><!-- open: 272, close: 272 --> <!-- MATCHED MATCHED MATCHED -->s get <!-- open: 273, close: 272 --><font class="lisp">setq</font><!-- open: 273, close: 273 --> <!-- MATCHED MATCHED MATCHED -->'ed to the values of their respective
<!-- open: 274, close: 273 --><font class="italic">repeat</font><!-- open: 274, close: 274 --> <!-- MATCHED MATCHED MATCHED -->s.  Note that all the <!-- open: 275, close: 274 --><font class="italic">repeat</font><!-- open: 275, close: 275 --> <!-- MATCHED MATCHED MATCHED -->s are evaluated before any
of the <!-- open: 276, close: 275 --><font class="italic">var</font><!-- open: 276, close: 276 --> <!-- MATCHED MATCHED MATCHED -->s is changed. 

The second element of the <!-- open: 277, close: 276 --><font class="lisp">do</font><!-- open: 277, close: 277 --> <!-- MATCHED MATCHED MATCHED -->-form is a list of an end-testing
predicate <!-- open: 278, close: 277 --><font class="italic">end-test</font><!-- open: 278, close: 278 --> <!-- MATCHED MATCHED MATCHED -->, and zero or more forms, called the
<!-- open: 279, close: 278 --><font class="italic">exit-form</font><!-- open: 279, close: 279 --> <!-- MATCHED MATCHED MATCHED -->s.  At the beginning of each iteration, after processing
of the <!-- open: 280, close: 279 --><font class="italic">repeat</font><!-- open: 280, close: 280 --> <!-- MATCHED MATCHED MATCHED -->s, the <!-- open: 281, close: 280 --><font class="italic">end-test</font><!-- open: 281, close: 281 --> <!-- MATCHED MATCHED MATCHED --> is evaluated.  If the result is
<!-- open: 282, close: 281 --><font class="lisp">nil</font><!-- open: 282, close: 282 --> <!-- MATCHED MATCHED MATCHED -->, execution proceeds with the body of the <!-- open: 283, close: 282 --><font class="lisp">do</font><!-- open: 283, close: 283 --> <!-- MATCHED MATCHED MATCHED -->.  If the
result is not <!-- open: 284, close: 283 --><font class="lisp">nil</font><!-- open: 284, close: 284 --> <!-- MATCHED MATCHED MATCHED -->, the <!-- open: 285, close: 284 --><font class="italic">exit-forms</font><!-- open: 285, close: 285 --> <!-- MATCHED MATCHED MATCHED --> are evaluated from left to
right and then <!-- open: 286, close: 285 --><font class="lisp">do</font><!-- open: 286, close: 286 --> <!-- MATCHED MATCHED MATCHED --> returns.  The value of the <!-- open: 287, close: 286 --><font class="lisp">do</font><!-- open: 287, close: 287 --> <!-- MATCHED MATCHED MATCHED --> is the value
of the last <!-- open: 288, close: 287 --><font class="italic">exit-form</font><!-- open: 288, close: 288 --> <!-- MATCHED MATCHED MATCHED -->, or <!-- open: 289, close: 288 --><font class="lisp">nil</font><!-- open: 289, close: 289 --> <!-- MATCHED MATCHED MATCHED --> (<!-- open: 290, close: 289 --><font class="italic">not</font><!-- open: 290, close: 290 --> <!-- MATCHED MATCHED MATCHED --> the value of the
<!-- open: 291, close: 290 --><font class="italic">end-test</font><!-- open: 291, close: 291 --> <!-- MATCHED MATCHED MATCHED --> as you might expect) if there were no <!-- open: 292, close: 291 --><font class="italic">exit-form</font><!-- open: 292, close: 292 --> <!-- MATCHED MATCHED MATCHED -->s. 
Note that the second element of the <!-- open: 293, close: 292 --><font class="lisp">do</font><!-- open: 293, close: 293 --> <!-- MATCHED MATCHED MATCHED -->-form resembles a <!-- open: 294, close: 293 --><font class="lisp">cond</font><!-- open: 294, close: 294 --> <!-- MATCHED MATCHED MATCHED -->
clause. 

If the second element of the form is <!-- open: 295, close: 294 --><font class="lisp">nil</font><!-- open: 295, close: 295 --> <!-- MATCHED MATCHED MATCHED -->, there is no <!-- open: 296, close: 295 --><font class="italic">end-test</font><!-- open: 296, close: 296 --> <!-- MATCHED MATCHED MATCHED -->
nor <!-- open: 297, close: 296 --><font class="italic">exit-form</font><!-- open: 297, close: 297 --> <!-- MATCHED MATCHED MATCHED -->s, and the <!-- open: 298, close: 297 --><font class="italic">body</font><!-- open: 298, close: 298 --> <!-- MATCHED MATCHED MATCHED --> of the <!-- open: 299, close: 298 --><font class="lisp">do</font><!-- open: 299, close: 299 --> <!-- MATCHED MATCHED MATCHED --> is executed only
once.  In this type of <!-- open: 300, close: 299 --><font class="lisp">do</font><!-- open: 300, close: 300 --> <!-- MATCHED MATCHED MATCHED --> it is an error to have <!-- open: 301, close: 300 --><font class="italic">repeat</font><!-- open: 301, close: 301 --> <!-- MATCHED MATCHED MATCHED -->s. 
This type of <!-- open: 302, close: 301 --><font class="lisp">do</font><!-- open: 302, close: 302 --> <!-- MATCHED MATCHED MATCHED --> is a "<!-- open: 303, close: 302 --><font class="lisp">prog</font><!-- open: 303, close: 303 --> <!-- MATCHED MATCHED MATCHED --> with initial values."

If the second element of the form is <!-- open: 304, close: 303 --><font class="lisp">(nil)</font><!-- open: 304, close: 304 --> <!-- MATCHED MATCHED MATCHED -->, the <!-- open: 305, close: 304 --><font class="italic">end-test</font><!-- open: 305, close: 305 --> <!-- MATCHED MATCHED MATCHED --> is never
true and there are no <!-- open: 306, close: 305 --><font class="italic">exit-form</font><!-- open: 306, close: 306 --> <!-- MATCHED MATCHED MATCHED -->s.  The <!-- open: 307, close: 306 --><font class="italic">body</font><!-- open: 307, close: 307 --> <!-- MATCHED MATCHED MATCHED --> of the <!-- open: 308, close: 307 --><font class="lisp">do</font><!-- open: 308, close: 308 --> <!-- MATCHED MATCHED MATCHED -->
is executed over and over. 
The infinite loop can be terminated by use of <!-- open: 309, close: 308 --><font class="lisp">return</font><!-- open: 309, close: 309 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 310, close: 309 --><font class="lisp">*throw</font><!-- open: 310, close: 310 --> <!-- MATCHED MATCHED MATCHED -->.

The remainder of the <!-- open: 311, close: 310 --><font class="lisp">do</font><!-- open: 311, close: 311 --> <!-- MATCHED MATCHED MATCHED -->-form constitutes a <!-- open: 312, close: 311 --><font class="lisp">prog</font><!-- open: 312, close: 312 --> <!-- MATCHED MATCHED MATCHED -->-body; that is,
<!-- open: 313, close: 312 --><font class="lisp">go</font><!-- open: 313, close: 313 --> <!-- MATCHED MATCHED MATCHED -->'s and <!-- open: 314, close: 313 --><font class="lisp">return</font><!-- open: 314, close: 314 --> <!-- MATCHED MATCHED MATCHED --> forms are understood within the <!-- open: 315, close: 314 --><font class="lisp">do</font><!-- open: 315, close: 315 --> <!-- MATCHED MATCHED MATCHED --> body,
as if it were a <!-- open: 316, close: 315 --><font class="lisp">prog</font><!-- open: 316, close: 316 --> <!-- MATCHED MATCHED MATCHED --> body.  When the end of the body is reached,
the next iteration of the <!-- open: 317, close: 316 --><font class="lisp">do</font><!-- open: 317, close: 317 --> <!-- MATCHED MATCHED MATCHED --> begins.  If a <!-- open: 318, close: 317 --><font class="lisp">return</font><!-- open: 318, close: 318 --> <!-- MATCHED MATCHED MATCHED --> form is evaluated,
<!-- open: 319, close: 318 --><font class="lisp">do</font><!-- open: 319, close: 319 --> <!-- MATCHED MATCHED MATCHED --> returns the indicated value and no more iterations occur. 

The older variety of <!-- open: 320, close: 319 --><font class="lisp">do</font><!-- open: 320, close: 320 --> <!-- MATCHED MATCHED MATCHED --> is:
<pre class='lisp'>
(do <!-- open: 321, close: 320 --><font class="italic">var</font><!-- open: 321, close: 321 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 322, close: 321 --><font class="italic">init</font><!-- open: 322, close: 322 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 323, close: 322 --><font class="italic">repeat</font><!-- open: 323, close: 323 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 324, close: 323 --><font class="italic">end-test</font><!-- open: 324, close: 324 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 325, close: 324 --><font class="italic">body</font><!-- open: 325, close: 325 --> <!-- MATCHED MATCHED MATCHED -->...)
</pre>
The first time through the loop <!-- open: 326, close: 325 --><font class="italic">var</font><!-- open: 326, close: 326 --> <!-- MATCHED MATCHED MATCHED --> gets the value of <!-- open: 327, close: 326 --><font class="italic">init</font><!-- open: 327, close: 327 --> <!-- MATCHED MATCHED MATCHED -->; 
the remaining times through the loop it gets the value of <!-- open: 328, close: 327 --><font class="italic">repeat</font><!-- open: 328, close: 328 --> <!-- MATCHED MATCHED MATCHED -->,
which is re-evaluated each time.  Note that <!-- open: 329, close: 328 --><font class="italic">init</font><!-- open: 329, close: 329 --> <!-- MATCHED MATCHED MATCHED --> is evaluated
before the value of <!-- open: 330, close: 329 --><font class="italic">var</font><!-- open: 330, close: 330 --> <!-- MATCHED MATCHED MATCHED --> is saved, i.e. lexically <!-- open: 331, close: 330 --><font class="italic">outside</font><!-- open: 331, close: 331 --> <!-- MATCHED MATCHED MATCHED --> of the <!-- open: 332, close: 331 --><font class="lisp">do</font><!-- open: 332, close: 332 --> <!-- MATCHED MATCHED MATCHED -->.
Each time around the loop, after <!-- open: 333, close: 332 --><font class="italic">var</font><!-- open: 333, close: 333 --> <!-- MATCHED MATCHED MATCHED --> is set,
<!-- open: 334, close: 333 --><font class="italic">end-test</font><!-- open: 334, close: 334 --> <!-- MATCHED MATCHED MATCHED --> is evaluated.  If it is non-<!-- open: 335, close: 334 --><font class="lisp">nil</font><!-- open: 335, close: 335 --> <!-- MATCHED MATCHED MATCHED -->, the <!-- open: 336, close: 335 --><font class="lisp">do</font><!-- open: 336, close: 336 --> <!-- MATCHED MATCHED MATCHED --> finishes
and returns <!-- open: 337, close: 336 --><font class="lisp">nil</font><!-- open: 337, close: 337 --> <!-- MATCHED MATCHED MATCHED -->.  If the <!-- open: 338, close: 337 --><font class="italic">end-test</font><!-- open: 338, close: 338 --> <!-- MATCHED MATCHED MATCHED --> evaluated to <!-- open: 339, close: 338 --><font class="lisp">nil</font><!-- open: 339, close: 339 --> <!-- MATCHED MATCHED MATCHED -->, the <!-- open: 340, close: 339 --><font class="italic">body</font><!-- open: 340, close: 340 --> <!-- MATCHED MATCHED MATCHED --> of
the loop is executed.  The <!-- open: 341, close: 340 --><font class="italic">body</font><!-- open: 341, close: 341 --> <!-- MATCHED MATCHED MATCHED --> is like a <!-- open: 342, close: 341 --><font class="lisp">prog</font><!-- open: 342, close: 342 --> <!-- MATCHED MATCHED MATCHED --> body.  <!-- open: 343, close: 342 --><font class="lisp">go</font><!-- open: 343, close: 343 --> <!-- MATCHED MATCHED MATCHED -->
may be used.  If <!-- open: 344, close: 343 --><font class="lisp">return</font><!-- open: 344, close: 344 --> <!-- MATCHED MATCHED MATCHED --> is used, its argument is the value of the
<!-- open: 345, close: 344 --><font class="lisp">do</font><!-- open: 345, close: 345 --> <!-- MATCHED MATCHED MATCHED -->.  If the end of the <!-- open: 346, close: 345 --><font class="lisp">prog</font><!-- open: 346, close: 346 --> <!-- MATCHED MATCHED MATCHED --> body is reached, another loop
begins. 

<pre class='lisp'>
<font class='exdent'>Examples of the older variety of <!-- open: 347, close: 346 --><font class="lisp">do</font><!-- open: 347, close: 347 --> <!-- MATCHED MATCHED MATCHED -->:
</font><!-- exdent -->(setq n (array-length foo-array))
(do i 0 (1+ i) (= i n)
  (aset 0 foo-array i))		<!-- open: 348, close: 347 --><font class="main">;zeroes out the array foo-array</font><!-- open: 348, close: 348 --> <!-- MATCHED MATCHED MATCHED -->

(do zz x (cdr zz) (or (null zz)
		      (zerop (f (car zz)))))
                   <!-- open: 349, close: 348 --><font class="main">; this applies f to each element of x
                   ; continuously until f returns zero.
		   ; Note that the <!-- open: 350, close: 348 --><font class="lisp">do</font><!-- open: 350, close: 349 --> has no body.</font><!-- open: 350, close: 350 --> <!-- MATCHED MATCHED MATCHED -->

<!-- open: 351, close: 350 --><font class="main"><!-- open: 352, close: 350 --><font class="lisp">return</font><!-- open: 352, close: 351 --> forms are often useful to do simple searches:</font><!-- open: 352, close: 352 --> <!-- MATCHED MATCHED MATCHED -->

(do i 0 (1+ i) (= i n)	<!-- open: 353, close: 352 --><font class="main">; Iterate over the length of <!-- open: 354, close: 352 --><font class="lisp">foo-array</font><!-- open: 354, close: 353 -->.</font><!-- open: 354, close: 354 --> <!-- MATCHED MATCHED MATCHED -->
  (and (= (aref foo-array i) 5)	<!-- open: 355, close: 354 --><font class="main">; If we find an element which
				;equals <!-- open: 356, close: 354 --><font class="lisp">5</font><!-- open: 356, close: 355 -->,</font><!-- open: 356, close: 356 --> <!-- MATCHED MATCHED MATCHED -->
       (return i)))	<!-- open: 357, close: 356 --><font class="main">;  then return its index.</font><!-- open: 357, close: 357 --> <!-- MATCHED MATCHED MATCHED -->

</pre>
<pre class='lisp'>
<font class='exdent'>Examples of the new form of <!-- open: 358, close: 357 --><font class="lisp">do</font><!-- open: 358, close: 358 --> <!-- MATCHED MATCHED MATCHED -->:
</font><!-- exdent -->(do ((i 0 (1+ i))	<!-- open: 359, close: 358 --><font class="main">; This is just the same as the above example,</font><!-- open: 359, close: 359 --> <!-- MATCHED MATCHED MATCHED -->
     (n (array-length foo-array)))
    ((= i n))		<!-- open: 360, close: 359 --><font class="main">; but written as a new-style <!-- open: 361, close: 359 --><font class="lisp">do</font><!-- open: 361, close: 360 -->.</font><!-- open: 361, close: 361 --> <!-- MATCHED MATCHED MATCHED -->
  (aset 0 foo-array i))

(do ((z list (cdr z)) <!-- open: 362, close: 361 --><font class="main">; z starts as <!-- open: 363, close: 361 --><font class="lisp">list</font><!-- open: 363, close: 362 --> and is <!-- open: 364, close: 362 --><font class="italic">cdr</font><!-- open: 364, close: 363 -->'ed each time.</font><!-- open: 364, close: 364 --> <!-- MATCHED MATCHED MATCHED -->
     (y other-list)   <!-- open: 365, close: 364 --><font class="main">; y starts as <!-- open: 366, close: 364 --><font class="lisp">other-list</font><!-- open: 366, close: 365 -->, and is unchanged by the do.</font><!-- open: 366, close: 366 --> <!-- MATCHED MATCHED MATCHED -->
     (x))	      <!-- open: 367, close: 366 --><font class="main">; x starts as <!-- open: 368, close: 366 --><font class="lisp">nil</font><!-- open: 368, close: 367 --> and is not changed by the <!-- open: 369, close: 367 --><font class="lisp">do</font><!-- open: 369, close: 368 -->.</font><!-- open: 369, close: 369 --> <!-- MATCHED MATCHED MATCHED -->
    (nil)	      <!-- open: 370, close: 369 --><font class="main">; The end-test is <!-- open: 371, close: 369 --><font class="lisp">nil</font><!-- open: 371, close: 370 -->, so this is an infinite loop.</font><!-- open: 371, close: 371 --> <!-- MATCHED MATCHED MATCHED -->
  <!-- open: 372, close: 371 --><font class="italic">body</font><!-- open: 372, close: 372 --> <!-- MATCHED MATCHED MATCHED -->)

(do ((x) (y) (z)) (nil) <!-- open: 373, close: 372 --><font class="italic">body</font><!-- open: 373, close: 373 --> <!-- MATCHED MATCHED MATCHED -->)

<!-- open: 374, close: 373 --><font class="main">is like</font><!-- open: 374, close: 374 --> <!-- MATCHED MATCHED MATCHED -->

(prog (x y z) <!-- open: 375, close: 374 --><font class="italic">body</font><!-- open: 375, close: 375 --> <!-- MATCHED MATCHED MATCHED -->)
<!-- open: 376, close: 375 --><font class="main">except that when it runs off the end of the <!-- open: 377, close: 375 --><font class="italic">body</font><!-- open: 377, close: 376 -->,
<!-- open: 378, close: 376 --><font class="lisp">do</font><!-- open: 378, close: 377 --> loops but <!-- open: 379, close: 377 --><font class="lisp">prog</font><!-- open: 379, close: 378 --> returns <!-- open: 380, close: 378 --><font class="lisp">nil</font><!-- open: 380, close: 379 -->.

On the other hand,</font><!-- open: 380, close: 380 --> <!-- MATCHED MATCHED MATCHED -->

     (do ((x) (y) (z)) nil <!-- open: 381, close: 380 --><font class="italic">body</font><!-- open: 381, close: 381 --> <!-- MATCHED MATCHED MATCHED -->)

<!-- open: 382, close: 381 --><font class="main">is identical to the <!-- open: 383, close: 381 --><font class="lisp">prog</font><!-- open: 383, close: 382 --> above (it does not loop.)</font><!-- open: 383, close: 383 --> <!-- MATCHED MATCHED MATCHED -->
</pre>

The construction
<pre class='lisp'>
(do ((x e (cdr x))
     (oldx x x))
    ((null x))
  <!-- open: 384, close: 383 --><font class="italic">body</font><!-- open: 384, close: 384 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
exploits parallel assignment to index variables.  On the first
iteration, the value of <!-- open: 385, close: 384 --><font class="lisp">oldx</font><!-- open: 385, close: 385 --> <!-- MATCHED MATCHED MATCHED --> is whatever value <!-- open: 386, close: 385 --><font class="lisp">x</font><!-- open: 386, close: 386 --> <!-- MATCHED MATCHED MATCHED --> had before
the <!-- open: 387, close: 386 --><font class="lisp">do</font><!-- open: 387, close: 387 --> <!-- MATCHED MATCHED MATCHED --> was entered.  On succeeding iterations, <!-- open: 388, close: 387 --><font class="lisp">oldx</font><!-- open: 388, close: 388 --> <!-- MATCHED MATCHED MATCHED --> contains
the value that <!-- open: 389, close: 388 --><font class="lisp">x</font><!-- open: 389, close: 389 --> <!-- MATCHED MATCHED MATCHED --> had on the previous iteration. 

In either form of <!-- open: 390, close: 389 --><font class="lisp">do</font><!-- open: 390, close: 390 --> <!-- MATCHED MATCHED MATCHED -->, the <!-- open: 391, close: 390 --><font class="italic">body</font><!-- open: 391, close: 391 --> <!-- MATCHED MATCHED MATCHED --> may contain no forms at all.
Very often an iterative algorithm can be most clearly expressed entirely
in the <!-- open: 392, close: 391 --><font class="italic">repeats</font><!-- open: 392, close: 392 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 393, close: 392 --><font class="italic">exit-forms</font><!-- open: 393, close: 393 --> <!-- MATCHED MATCHED MATCHED --> of a new-style <!-- open: 394, close: 393 --><font class="lisp">do</font><!-- open: 394, close: 394 --> <!-- MATCHED MATCHED MATCHED -->,
and the <!-- open: 395, close: 394 --><font class="italic">body</font><!-- open: 395, close: 395 --> <!-- MATCHED MATCHED MATCHED --> is empty.

<pre class='lisp'>
(do ((x x (cdr x))
     (y y (cdr y))
     (z nil (cons (f x y) z))) ;<!-- open: 396, close: 395 --><font class="main">exploits parallel</font><!-- open: 396, close: 396 --> <!-- MATCHED MATCHED MATCHED -->
    ((or (null x) (null y))    ;<!-- open: 397, close: 396 --><font class="main"> assignment.</font><!-- open: 397, close: 397 --> <!-- MATCHED MATCHED MATCHED -->
     (nreverse z))             ;<!-- open: 398, close: 397 --><font class="main">typical use of </font><!-- open: 398, close: 398 --> <!-- MATCHED MATCHED MATCHED -->nreverse.
    )                          ;<!-- open: 399, close: 398 --><font class="main">no <!-- open: 400, close: 398 --><font class="lisp">do</font><!-- open: 400, close: 399 -->-body required.</font><!-- open: 400, close: 400 --> <!-- MATCHED MATCHED MATCHED -->

<!-- open: 401, close: 400 --><font class="main">is like</font><!-- open: 401, close: 401 --> <!-- MATCHED MATCHED MATCHED --> (maplist 'f x y).
</pre>
</div>

<div class='defspec' id='do-named'><font class='exdent'><font class='funcname' id='do-named'>do-named</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 402, close: 401 --><font class="lisp">do-named</font><!-- open: 402, close: 402 --> <!-- MATCHED MATCHED MATCHED --> is just like <!-- open: 403, close: 402 --><font class="lisp">do</font><!-- open: 403, close: 403 --> <!-- MATCHED MATCHED MATCHED --> except that its first subform
is a symbol, which is interpreted as the <!-- open: 404, close: 403 --><font class="italic">name</font><!-- open: 404, close: 404 --> <!-- MATCHED MATCHED MATCHED --> of the <!-- open: 405, close: 404 --><font class="lisp">do</font><!-- open: 405, close: 405 --> <!-- MATCHED MATCHED MATCHED -->.
The <!-- open: 406, close: 405 --><font class="lisp">return-from</font><!-- open: 406, close: 406 --> <!-- MATCHED MATCHED MATCHED --> special form allows a <!-- open: 407, close: 406 --><font class="lisp">return</font><!-- open: 407, close: 407 --> <!-- MATCHED MATCHED MATCHED --> from
a particular <!-- open: 408, close: 407 --><font class="lisp">prog</font><!-- open: 408, close: 408 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 409, close: 408 --><font class="lisp">do-named</font><!-- open: 409, close: 409 --> <!-- MATCHED MATCHED MATCHED --> when several are nested.
See the description of such names in the explanation of the <!-- open: 410, close: 409 --><font class="lisp">prog</font><!-- open: 410, close: 410 --> <!-- MATCHED MATCHED MATCHED -->
special form on <font color='red'>LINK:(</font>prog-fun), and that of <!-- open: 411, close: 410 --><font class="lisp">return-from</font><!-- open: 411, close: 411 --> <!-- MATCHED MATCHED MATCHED --> on <font color='red'>LINK:(</font>return-from-fun).
</div>

<div class='defspec' id='dotimes'><font class='exdent'><font class='funcname' id='dotimes'>dotimes</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 412, close: 411 --><font class="lisp">dotimes</font><!-- open: 412, close: 412 --> <!-- MATCHED MATCHED MATCHED --> is a convenient abbreviation for the most common integer iteration.
<!-- open: 413, close: 412 --><font class="lisp">(dotimes (<!-- open: 414, close: 412 --><font class="italic">index</font><!-- open: 414, close: 413 --> <!-- open: 415, close: 413 --><font class="italic">count</font><!-- open: 415, close: 414 -->) <!-- open: 416, close: 414 --><font class="italic">body...</font><!-- open: 416, close: 415 -->)</font><!-- open: 416, close: 416 --> <!-- MATCHED MATCHED MATCHED --> performs <!-- open: 417, close: 416 --><font class="italic">body</font><!-- open: 417, close: 417 --> <!-- MATCHED MATCHED MATCHED -->
the number of times given by the value of <!-- open: 418, close: 417 --><font class="italic">count</font><!-- open: 418, close: 418 --> <!-- MATCHED MATCHED MATCHED -->, with <!-- open: 419, close: 418 --><font class="italic">index</font><!-- open: 419, close: 419 --> <!-- MATCHED MATCHED MATCHED --> bound
to <!-- open: 420, close: 419 --><font class="lisp">0</font><!-- open: 420, close: 420 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 421, close: 420 --><font class="lisp">1</font><!-- open: 421, close: 421 --> <!-- MATCHED MATCHED MATCHED -->, etc. on successive iterations.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(dotimes (i (// m n)
  (frob i))
<font class='exdent'><!-- open: 422, close: 421 --><font class="main">is equivalent to:</font><!-- open: 422, close: 422 --> <!-- MATCHED MATCHED MATCHED -->
</font><!-- exdent -->(do ((i 0 (1+ i))
     (count (// m n)))
    ((&ge; i count))
  (frob i))
<font class='exdent'><!-- open: 423, close: 422 --><font class="main">except that the name <!-- open: 424, close: 422 --><font class="lisp">count</font><!-- open: 424, close: 423 --> is not used.</font><!-- open: 424, close: 424 --> <!-- MATCHED MATCHED MATCHED -->
</font><!-- exdent --></pre>
</div>

<div class='defspec' id='dolist'><font class='exdent'><font class='funcname' id='dolist'>dolist</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 425, close: 424 --><font class="lisp">dolist</font><!-- open: 425, close: 425 --> <!-- MATCHED MATCHED MATCHED --> is a convenient abbreviation for the most common list iteration.
<!-- open: 426, close: 425 --><font class="lisp">(dolist (<!-- open: 427, close: 425 --><font class="italic">item</font><!-- open: 427, close: 426 --> <!-- open: 428, close: 426 --><font class="italic">list</font><!-- open: 428, close: 427 -->) <!-- open: 429, close: 427 --><font class="italic">body...</font><!-- open: 429, close: 428 -->)</font><!-- open: 429, close: 429 --> <!-- MATCHED MATCHED MATCHED --> performs <!-- open: 430, close: 429 --><font class="italic">body</font><!-- open: 430, close: 430 --> <!-- MATCHED MATCHED MATCHED -->
once for each element in the list which is the value of <!-- open: 431, close: 430 --><font class="italic">list</font><!-- open: 431, close: 431 --> <!-- MATCHED MATCHED MATCHED -->, with
<!-- open: 432, close: 431 --><font class="italic">item</font><!-- open: 432, close: 432 --> <!-- MATCHED MATCHED MATCHED --> bound to the successive elements.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(dolist (item (frobs foo))
  (mung item))
<font class='exdent'><!-- open: 433, close: 432 --><font class="main">is equivalent to:</font><!-- open: 433, close: 433 --> <!-- MATCHED MATCHED MATCHED -->
</font><!-- exdent -->(do ((lst (frobs foo) (cdr lst))
     (item))
    ((null lst))
  (setq item (car lst))
  (mung item))
<font class='exdent'><!-- open: 434, close: 433 --><font class="main">except that the name <!-- open: 435, close: 433 --><font class="lisp">lst</font><!-- open: 435, close: 434 --> is not used.</font><!-- open: 435, close: 435 --> <!-- MATCHED MATCHED MATCHED -->
</font><!-- exdent --></pre>
</div>

<div class='defspec' id='go'><font class='exdent'><font class='funcname' id='go'>go</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->The <!-- open: 436, close: 435 --><font class="lisp">(go <!-- open: 437, close: 435 --><font class="italic">tag</font><!-- open: 437, close: 436 -->)</font><!-- open: 437, close: 437 --> <!-- MATCHED MATCHED MATCHED --> special form is used to do a "go-to" within the
body of a <!-- open: 438, close: 437 --><font class="lisp">do</font><!-- open: 438, close: 438 --> <!-- MATCHED MATCHED MATCHED --> or a <!-- open: 439, close: 438 --><font class="lisp">prog</font><!-- open: 439, close: 439 --> <!-- MATCHED MATCHED MATCHED -->.  The <!-- open: 440, close: 439 --><font class="italic">tag</font><!-- open: 440, close: 440 --> <!-- MATCHED MATCHED MATCHED --> must be a symbol.
It is not evaluated. <!-- open: 441, close: 440 --><font class="lisp">go</font><!-- open: 441, close: 441 --> <!-- MATCHED MATCHED MATCHED --> transfers control to the point in the body labelled by a
tag <!-- open: 442, close: 441 --><font class="lisp">eq</font><!-- open: 442, close: 442 --> <!-- MATCHED MATCHED MATCHED --> to the one given.  If there is no such tag in the body, the
bodies of lexically containing <!-- open: 443, close: 442 --><font class="lisp">prog</font><!-- open: 443, close: 443 --> <!-- MATCHED MATCHED MATCHED -->s and <!-- open: 444, close: 443 --><font class="lisp">do</font><!-- open: 444, close: 444 --> <!-- MATCHED MATCHED MATCHED -->s (if any) are examined as well.
If no tag is found, an error is signalled.
	Note that the <!-- open: 445, close: 444 --><font class="lisp">go</font><!-- open: 445, close: 445 --> <!-- MATCHED MATCHED MATCHED --> form is a very special form: it does not ever
return a value.  A <!-- open: 446, close: 445 --><font class="lisp">go</font><!-- open: 446, close: 446 --> <!-- MATCHED MATCHED MATCHED --> form may not appear as an argument to a regular
function, but only at the top level of a <!-- open: 447, close: 446 --><font class="lisp">prog</font><!-- open: 447, close: 447 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 448, close: 447 --><font class="lisp">do</font><!-- open: 448, close: 448 --> <!-- MATCHED MATCHED MATCHED -->,
or within certain special forms such as conditionals which are within
a <!-- open: 449, close: 448 --><font class="lisp">prog</font><!-- open: 449, close: 449 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 450, close: 449 --><font class="lisp">do</font><!-- open: 450, close: 450 --> <!-- MATCHED MATCHED MATCHED -->.
A <!-- open: 451, close: 450 --><font class="lisp">go</font><!-- open: 451, close: 451 --> <!-- MATCHED MATCHED MATCHED --> as an argument to a regular function would be not only useless but
possibly meaningless.  The compiler does not bother to know how to compile it
correctly.  <!-- open: 452, close: 451 --><font class="lisp">return</font><!-- open: 452, close: 452 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 453, close: 452 --><font class="lisp">*throw</font><!-- open: 453, close: 453 --> <!-- MATCHED MATCHED MATCHED --> are similar.
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(prog (x y z)
  (setq x <!-- open: 454, close: 453 --><font class="italic">some frob</font><!-- open: 454, close: 454 --> <!-- MATCHED MATCHED MATCHED -->)
loop
  <!-- open: 455, close: 454 --><font class="italic">do something</font><!-- open: 455, close: 455 --> <!-- MATCHED MATCHED MATCHED -->
  (and <!-- open: 456, close: 455 --><font class="italic">some predicate</font><!-- open: 456, close: 456 --> <!-- MATCHED MATCHED MATCHED --> (go endtag))
  <!-- open: 457, close: 456 --><font class="italic">do something more</font><!-- open: 457, close: 457 --> <!-- MATCHED MATCHED MATCHED -->
  (and (minusp x) (go loop))
endtag
  (return z))
</pre>
</div>

<div class='defun' id='return'>
  <font class='exdent'>
    <font class='funcname'>return </font>
    <font class='italic' color='purple'>arg</font>
  </font><br>
<!-- open: 458, close: 457 --><font class="lisp">return</font><!-- open: 458, close: 458 --> <!-- MATCHED MATCHED MATCHED --> is used to return from a <!-- open: 459, close: 458 --><font class="lisp">prog</font><!-- open: 459, close: 459 --> <!-- MATCHED MATCHED MATCHED --> or a <!-- open: 460, close: 459 --><font class="lisp">do</font><!-- open: 460, close: 460 --> <!-- MATCHED MATCHED MATCHED -->.  The value
of <!-- open: 461, close: 460 --><font class="lisp">return</font><!-- open: 461, close: 461 --> <!-- MATCHED MATCHED MATCHED -->'s argument is returned by <!-- open: 462, close: 461 --><font class="lisp">prog</font><!-- open: 462, close: 462 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 463, close: 462 --><font class="lisp">do</font><!-- open: 463, close: 463 --> <!-- MATCHED MATCHED MATCHED --> as its
value.  In addition, <!-- open: 464, close: 463 --><font class="lisp">break</font><!-- open: 464, close: 464 --> <!-- MATCHED MATCHED MATCHED --> recognizes the typed-in S-expression
<!-- open: 465, close: 464 --><font class="lisp">(return <!-- open: 466, close: 464 --><font class="italic">value</font><!-- open: 466, close: 465 -->)</font><!-- open: 466, close: 466 --> <!-- MATCHED MATCHED MATCHED --> specially.  If this form is typed at a
<!-- open: 467, close: 466 --><font class="lisp">break</font><!-- open: 467, close: 467 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 468, close: 467 --><font class="italic">value</font><!-- open: 468, close: 468 --> <!-- MATCHED MATCHED MATCHED --> will be evaluated and returned as the value of
<!-- open: 469, close: 468 --><font class="lisp">break</font><!-- open: 469, close: 469 --> <!-- MATCHED MATCHED MATCHED -->.  If not at the top level of a form typed at a <!-- open: 470, close: 469 --><font class="lisp">break</font><!-- open: 470, close: 470 --> <!-- MATCHED MATCHED MATCHED -->,
and not inside a <!-- open: 471, close: 470 --><font class="lisp">prog</font><!-- open: 471, close: 471 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 472, close: 471 --><font class="lisp">do</font><!-- open: 472, close: 472 --> <!-- MATCHED MATCHED MATCHED -->, <!-- open: 473, close: 472 --><font class="lisp">return</font><!-- open: 473, close: 473 --> <!-- MATCHED MATCHED MATCHED --> will cause an
error. 
<!-- Does our BREAK hack this yet? -->
<pre class='lisp'>
<font class='exdent'>Example:
</font><!-- exdent -->(do ((x x (cdr x))
     (n 0 (* n 2)))
    ((null x) n)
 (cond ((atom (car x))
        (setq n (1+ n)))
       ((memq (caar x) '(sys boom bleah))
        (return n))))
</pre>
<!-- open: 474, close: 473 --><font class="lisp">return</font><!-- open: 474, close: 474 --> <!-- MATCHED MATCHED MATCHED --> is, like <!-- open: 475, close: 474 --><font class="lisp">go</font><!-- open: 475, close: 475 --> <!-- MATCHED MATCHED MATCHED -->, a special form which does not return a value.

<!-- open: 476, close: 475 --><font class="lisp">return</font><!-- open: 476, close: 476 --> <!-- MATCHED MATCHED MATCHED --> can also be used to return multiple values from a <!-- open: 477, close: 476 --><font class="lisp">prog</font><!-- open: 477, close: 477 --> <!-- MATCHED MATCHED MATCHED --> or
<!-- open: 478, close: 477 --><font class="lisp">do</font><!-- open: 478, close: 478 --> <!-- MATCHED MATCHED MATCHED -->, by giving it multiple arguments.  For example,
<pre class='lisp'>
(defun assqn (x table)
  (do ((l table (cdr l))
       (n 0 (1+ n)))
      ((null l) nil)
    (and (eq (caar l) x)
	 (return (car l) n))))
</pre>
This function is like <!-- open: 479, close: 478 --><font class="lisp">assq</font><!-- open: 479, close: 479 --> <!-- MATCHED MATCHED MATCHED -->, but it returns an additional value
which is the index in the table of the entry it found.
See the special forms <!-- open: 480, close: 479 --><font class="lisp">multiple-value</font><!-- open: 480, close: 480 --> <!-- MATCHED MATCHED MATCHED --> (<font color='red'>LINK:(</font>multiple-value-fun))
and <!-- open: 481, close: 480 --><font class="lisp">multiple-value-list</font><!-- open: 481, close: 481 --> <!-- MATCHED MATCHED MATCHED --> (<font color='red'>LINK:(</font>multiple-value-list-fun)).
</div>

<div class='defspec' id='return-from'><font class='exdent'><font class='funcname' id='return-from'>return-from</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent -->A <!-- open: 482, close: 481 --><font class="lisp">return-from</font><!-- open: 482, close: 482 --> <!-- MATCHED MATCHED MATCHED --> form looks like <!-- open: 483, close: 482 --><font class="lisp">(return-from <!-- open: 484, close: 482 --><font class="italic">name form1 form2 form3</font><!-- open: 484, close: 483 -->)</font><!-- open: 484, close: 484 --> <!-- MATCHED MATCHED MATCHED -->.
The <!-- open: 485, close: 484 --><font class="italic">form</font><!-- open: 485, close: 485 --> <!-- MATCHED MATCHED MATCHED -->s are evaluated sequentially, and then are returned
from the innermost containing <!-- open: 486, close: 485 --><font class="lisp">prog</font><!-- open: 486, close: 486 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 487, close: 486 --><font class="lisp">do-named</font><!-- open: 487, close: 487 --> <!-- MATCHED MATCHED MATCHED --> whose name
is <!-- open: 488, close: 487 --><font class="italic">name</font><!-- open: 488, close: 488 --> <!-- MATCHED MATCHED MATCHED -->.  See the description of <!-- open: 489, close: 488 --><font class="lisp">prog</font><!-- open: 489, close: 489 --> <!-- MATCHED MATCHED MATCHED --> (<font color='red'>LINK:(</font>prog-fun)) in which
named <!-- open: 490, close: 489 --><font class="lisp">prog</font><!-- open: 490, close: 490 --> <!-- MATCHED MATCHED MATCHED -->s and <!-- open: 491, close: 490 --><font class="lisp">do</font><!-- open: 491, close: 491 --> <!-- MATCHED MATCHED MATCHED -->s are explained, and that of <!-- open: 492, close: 491 --><font class="lisp">do-named</font><!-- open: 492, close: 492 --> <!-- MATCHED MATCHED MATCHED --> (<font color='red'>LINK:(</font>do-named-fun)).
</div>

<div class='defun' id='return-list'>
  <font class='exdent'>
    <font class='funcname'>return-list </font>
    <font class='italic' color='purple'>list</font>
  </font><br>
<!-- open: 493, close: 492 --><font class="italic">list</font><!-- open: 493, close: 493 --> <!-- MATCHED MATCHED MATCHED --> must not be <!-- open: 494, close: 493 --><font class="lisp">nil</font><!-- open: 494, close: 494 --> <!-- MATCHED MATCHED MATCHED -->.  This function is like <!-- open: 495, close: 494 --><font class="lisp">return</font><!-- open: 495, close: 495 --> <!-- MATCHED MATCHED MATCHED --> except
that the <!-- open: 496, close: 495 --><font class="lisp">prog</font><!-- open: 496, close: 496 --> <!-- MATCHED MATCHED MATCHED --> returns all of the elements of <!-- open: 497, close: 496 --><font class="italic">list</font><!-- open: 497, close: 497 --> <!-- MATCHED MATCHED MATCHED -->; if
<!-- open: 498, close: 497 --><font class="italic">list</font><!-- open: 498, close: 498 --> <!-- MATCHED MATCHED MATCHED --> has more then one element, the <!-- open: 499, close: 498 --><font class="lisp">prog</font><!-- open: 499, close: 499 --> <!-- MATCHED MATCHED MATCHED --> does a multiple-value
return.
<!-- What is this good for? -->
	To direct the returned values to a <!-- open: 500, close: 499 --><font class="lisp">prog</font><!-- open: 500, close: 500 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 501, close: 500 --><font class="lisp">do-named</font><!-- open: 501, close: 501 --> <!-- MATCHED MATCHED MATCHED --> of a specific
name, use <!-- open: 502, close: 501 --><font class="lisp">(return-from <!-- open: 503, close: 501 --><font class="italic">name</font><!-- open: 503, close: 502 --> (return-list <!-- open: 504, close: 502 --><font class="italic">list</font><!-- open: 504, close: 503 -->))</font><!-- open: 504, close: 504 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='defspec' id='multiple-value-return'><font class='exdent'><font class='funcname' id='multiple-value-return'>multiple-value-return</font><font class="italic"> Special Form</font></br></font><!-- end font_exdent --><!-- open: 505, close: 504 --><font class="lisp">(multiple-value-return (<!-- open: 506, close: 504 --><font class="italic">function</font><!-- open: 506, close: 505 --> <!-- open: 507, close: 505 --><font class="italic">arg1</font><!-- open: 507, close: 506 --> <!-- open: 508, close: 506 --><font class="italic">arg2</font><!-- open: 508, close: 507 --> ...))</font><!-- open: 508, close: 508 --> <!-- MATCHED MATCHED MATCHED -->
applies the function to the arguments, and returns from the current <!-- open: 509, close: 508 --><font class="lisp">prog</font><!-- open: 509, close: 509 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 510, close: 509 --><font class="lisp">do</font><!-- open: 510, close: 510 --> <!-- MATCHED MATCHED MATCHED -->
with the same values as <!-- open: 511, close: 510 --><font class="italic">function</font><!-- open: 511, close: 511 --> <!-- MATCHED MATCHED MATCHED --> returns.
</div>

<div class='defmac' id='defunp'><font class='exdent'><font class='funcname' id='defunp'>defunp</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->Usually when a function uses <!-- open: 512, close: 511 --><font class="lisp">prog</font><!-- open: 512, close: 512 --> <!-- MATCHED MATCHED MATCHED -->, the <!-- open: 513, close: 512 --><font class="lisp">prog</font><!-- open: 513, close: 513 --> <!-- MATCHED MATCHED MATCHED --> form is
the entire body of the function; the definition of such a function
looks like <!-- open: 514, close: 513 --><font class="lisp">(defun <!-- open: 515, close: 513 --><font class="italic">name</font><!-- open: 515, close: 514 --> <!-- open: 516, close: 514 --><font class="italic">arglist</font><!-- open: 516, close: 515 --> (prog <!-- open: 517, close: 515 --><font class="italic">varlist</font><!-- open: 517, close: 516 --> ...))</font><!-- open: 517, close: 517 --> <!-- MATCHED MATCHED MATCHED -->.
For convenience, the <!-- open: 518, close: 517 --><font class="lisp">defunp</font><!-- open: 518, close: 518 --> <!-- MATCHED MATCHED MATCHED --> macro can be used to produce such definitions.
A <!-- open: 519, close: 518 --><font class="lisp">defunp</font><!-- open: 519, close: 519 --> <!-- MATCHED MATCHED MATCHED --> form expands as follows:
<pre class='lisp'>
(defunp fctn (args)
    form1
    form2
    ...
    formn)
</pre>
expands into
<pre class='lisp'>
(defun fctn (args)
  (prog nil
	form1
	form2
	...
	(return formn)))
</pre>
</div>

<div class='section' id='6.3'>6.3 Non-local Exits</div><p class='cindent'><!-- "non-local exit" -->
<p class='cindent'><!-- catch -->
<p class='cindent'><!-- throw -->

<div class='defun' id='*catch'>
  <font class='exdent'>
    <font class='funcname'>*catch </font>
    <font class='italic' color='purple'>tag form</font>
  </font><br>
<!-- open: 520, close: 519 --><font class="lisp">*catch</font><!-- open: 520, close: 520 --> <!-- MATCHED MATCHED MATCHED --> is the Lisp Machine Lisp function for doing structured
non-local exits.  <!-- open: 521, close: 520 --><font class="lisp">(*catch <!-- open: 522, close: 520 --><font class="italic">tag form</font><!-- open: 522, close: 521 -->)</font><!-- open: 522, close: 522 --> <!-- MATCHED MATCHED MATCHED --> evaluates <!-- open: 523, close: 522 --><font class="italic">form</font><!-- open: 523, close: 523 --> <!-- MATCHED MATCHED MATCHED --> and
returns its value, except that if, during the evaluation of <!-- open: 524, close: 523 --><font class="italic">form</font><!-- open: 524, close: 524 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 525, close: 524 --><font class="lisp">(*throw <!-- open: 526, close: 524 --><font class="italic">tag y</font><!-- open: 526, close: 525 -->)</font><!-- open: 526, close: 526 --> <!-- MATCHED MATCHED MATCHED --> should be evaluated, <!-- open: 527, close: 526 --><font class="lisp">*catch</font><!-- open: 527, close: 527 --> <!-- MATCHED MATCHED MATCHED --> immediately returns
<!-- open: 528, close: 527 --><font class="italic">y</font><!-- open: 528, close: 528 --> <!-- MATCHED MATCHED MATCHED --> without further evaluating <!-- open: 529, close: 528 --><font class="italic">x</font><!-- open: 529, close: 529 --> <!-- MATCHED MATCHED MATCHED -->.  Note that the <!-- open: 530, close: 529 --><font class="italic">form</font><!-- open: 530, close: 530 --> <!-- MATCHED MATCHED MATCHED --> argument
is <!-- open: 531, close: 530 --><font class="italic">not</font><!-- open: 531, close: 531 --> <!-- MATCHED MATCHED MATCHED --> evaluated twice; the special action of <!-- open: 532, close: 531 --><font class="lisp">*catch</font><!-- open: 532, close: 532 --> <!-- MATCHED MATCHED MATCHED --> happens
during the evaluation of its arguments, not during the execution of <!-- open: 533, close: 532 --><font class="lisp">*catch</font><!-- open: 533, close: 533 --> <!-- MATCHED MATCHED MATCHED -->
itself.

The <!-- open: 534, close: 533 --><font class="italic">tag</font><!-- open: 534, close: 534 --> <!-- MATCHED MATCHED MATCHED -->'s are used to match up <!-- open: 535, close: 534 --><font class="lisp">*throw</font><!-- open: 535, close: 535 --> <!-- MATCHED MATCHED MATCHED -->'s with <!-- open: 536, close: 535 --><font class="lisp">*catch</font><!-- open: 536, close: 536 --> <!-- MATCHED MATCHED MATCHED -->'s. 
<!-- open: 537, close: 536 --><font class="lisp">(*catch 'foo <!-- open: 538, close: 536 --><font class="italic">form</font><!-- open: 538, close: 537 -->)</font><!-- open: 538, close: 538 --> <!-- MATCHED MATCHED MATCHED --> will catch a <!-- open: 539, close: 538 --><font class="lisp">(*throw 'foo <!-- open: 540, close: 538 --><font class="italic">form</font><!-- open: 540, close: 539 -->)</font><!-- open: 540, close: 540 --> <!-- MATCHED MATCHED MATCHED --> but
not a <!-- open: 541, close: 540 --><font class="lisp">(*throw 'bar <!-- open: 542, close: 540 --><font class="italic">form</font><!-- open: 542, close: 541 -->)</font><!-- open: 542, close: 542 --> <!-- MATCHED MATCHED MATCHED -->.  It is an error if <!-- open: 543, close: 542 --><font class="lisp">*throw</font><!-- open: 543, close: 543 --> <!-- MATCHED MATCHED MATCHED --> is done
when there is no suitable <!-- open: 544, close: 543 --><font class="lisp">*catch</font><!-- open: 544, close: 544 --> <!-- MATCHED MATCHED MATCHED --> (or <!-- open: 545, close: 544 --><font class="lisp">catch-all</font><!-- open: 545, close: 545 --> <!-- MATCHED MATCHED MATCHED -->; see below). 

The values <!-- open: 546, close: 545 --><font class="lisp">t</font><!-- open: 546, close: 546 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 547, close: 546 --><font class="lisp">nil</font><!-- open: 547, close: 547 --> <!-- MATCHED MATCHED MATCHED --> for <!-- open: 548, close: 547 --><font class="italic">tag</font><!-- open: 548, close: 548 --> <!-- MATCHED MATCHED MATCHED --> are special and mean that all
throws are to be caught.  These are used by <!-- open: 549, close: 548 --><font class="lisp">unwind-protect</font><!-- open: 549, close: 549 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 550, close: 549 --><font class="lisp">catch-all</font><!-- open: 550, close: 550 --> <!-- MATCHED MATCHED MATCHED -->
respectively.  The only difference between <!-- open: 551, close: 550 --><font class="lisp">t</font><!-- open: 551, close: 551 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 552, close: 551 --><font class="lisp">nil</font><!-- open: 552, close: 552 --> <!-- MATCHED MATCHED MATCHED --> is in the
error checking; <!-- open: 553, close: 552 --><font class="lisp">t</font><!-- open: 553, close: 553 --> <!-- MATCHED MATCHED MATCHED --> implies that after a "cleanup handler" is executed
control will be thrown again to the same tag, therefore it is an error if a specific
catch for this tag does not exist higher up in the stack.

<!-- open: 554, close: 553 --><font class="lisp">*catch</font><!-- open: 554, close: 554 --> <!-- MATCHED MATCHED MATCHED --> returns up to four values; trailing null values are not
returned for reasons of microcode simplicity, however the values not
returned will default to <!-- open: 555, close: 554 --><font class="lisp">nil</font><!-- open: 555, close: 555 --> <!-- MATCHED MATCHED MATCHED --> if they are received with the
<!-- open: 556, close: 555 --><font class="lisp">multiple-value</font><!-- open: 556, close: 556 --> <!-- MATCHED MATCHED MATCHED --> special form.
If the catch completes normally,
the first value is the value of <!-- open: 557, close: 556 --><font class="italic">form</font><!-- open: 557, close: 557 --> <!-- MATCHED MATCHED MATCHED --> and the second is <!-- open: 558, close: 557 --><font class="lisp">nil</font><!-- open: 558, close: 558 --> <!-- MATCHED MATCHED MATCHED -->.
If a <!-- open: 559, close: 558 --><font class="lisp">*throw</font><!-- open: 559, close: 559 --> <!-- MATCHED MATCHED MATCHED --> occurs, the first value is the second argument to
<!-- open: 560, close: 559 --><font class="lisp">*throw</font><!-- open: 560, close: 560 --> <!-- MATCHED MATCHED MATCHED -->, and the second value is the first argument to <!-- open: 561, close: 560 --><font class="lisp">*throw</font><!-- open: 561, close: 561 --> <!-- MATCHED MATCHED MATCHED -->,
the tag thrown to.  The third and fourth values are the third and fourth
arguments to <!-- open: 562, close: 561 --><font class="lisp">*unwind-stack</font><!-- open: 562, close: 562 --> <!-- MATCHED MATCHED MATCHED --> if that was used in place of <!-- open: 563, close: 562 --><font class="lisp">*throw</font><!-- open: 563, close: 563 --> <!-- MATCHED MATCHED MATCHED -->,
otherwise <!-- open: 564, close: 563 --><font class="lisp">nil</font><!-- open: 564, close: 564 --> <!-- MATCHED MATCHED MATCHED -->.
To summarize, the four values returned by <!-- open: 565, close: 564 --><font class="lisp">*catch</font><!-- open: 565, close: 565 --> <!-- MATCHED MATCHED MATCHED --> are the value,
the tag, the active-frame-count, and the action.
<pre class='lisp'>
<font class='exdent'>Example
</font><!-- exdent -->(*catch 'negative
	(mapcar (function (lambda (x) 
                            (cond ((minusp x)
				   (*throw 'negative x))
				  (t (f x)) )))
               y)
     )
</pre>
which returns a list of <!-- open: 566, close: 565 --><font class="lisp">f</font><!-- open: 566, close: 566 --> <!-- MATCHED MATCHED MATCHED --> of each element of <!-- open: 567, close: 566 --><font class="lisp">y</font><!-- open: 567, close: 567 --> <!-- MATCHED MATCHED MATCHED --> if they are all
positive, otherwise the first negative member of <!-- open: 568, close: 567 --><font class="lisp">y</font><!-- open: 568, close: 568 --> <!-- MATCHED MATCHED MATCHED -->. 

Note: The Lisp Machine Lisp functions <!-- open: 569, close: 568 --><font class="lisp">*catch</font><!-- open: 569, close: 569 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 570, close: 569 --><font class="lisp">*throw</font><!-- open: 570, close: 570 --> <!-- MATCHED MATCHED MATCHED --> are
improved versions of the Maclisp functions <!-- open: 571, close: 570 --><font class="lisp">catch</font><!-- open: 571, close: 571 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 572, close: 571 --><font class="lisp">throw</font><!-- open: 572, close: 572 --> <!-- MATCHED MATCHED MATCHED -->. 
The Maclisp ones are similar in purpose, but take their arguments in
reversed order, do not evaluate the <!-- open: 573, close: 572 --><font class="italic">tag</font><!-- open: 573, close: 573 --> <!-- MATCHED MATCHED MATCHED -->, and may be used in an older form
in which no <!-- open: 574, close: 573 --><font class="italic">tag</font><!-- open: 574, close: 574 --> <!-- MATCHED MATCHED MATCHED --> is supplied.  Compatibility macros are supplied so
that programs using the Maclisp functions will work.
</div>

<div class='defun' id='*throw'>
  <font class='exdent'>
    <font class='funcname'>*throw </font>
    <font class='italic' color='purple'>tag value</font>
  </font><br>
<!-- open: 575, close: 574 --><font class="lisp">*throw</font><!-- open: 575, close: 575 --> <!-- MATCHED MATCHED MATCHED --> is used with <!-- open: 576, close: 575 --><font class="lisp">*catch</font><!-- open: 576, close: 576 --> <!-- MATCHED MATCHED MATCHED --> as a structured non-local exit mechanism.

<!-- open: 577, close: 576 --><font class="lisp">(*throw <!-- open: 578, close: 576 --><font class="italic">tag x</font><!-- open: 578, close: 577 -->)</font><!-- open: 578, close: 578 --> <!-- MATCHED MATCHED MATCHED --> throws the value of <!-- open: 579, close: 578 --><font class="italic">x</font><!-- open: 579, close: 579 --> <!-- MATCHED MATCHED MATCHED --> back to the most recent <!-- open: 580, close: 579 --><font class="lisp">*catch</font><!-- open: 580, close: 580 --> <!-- MATCHED MATCHED MATCHED -->
labelled with <!-- open: 581, close: 580 --><font class="italic">tag</font><!-- open: 581, close: 581 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 582, close: 581 --><font class="lisp">t</font><!-- open: 582, close: 582 --> <!-- MATCHED MATCHED MATCHED --> or <!-- open: 583, close: 582 --><font class="lisp">nil</font><!-- open: 583, close: 583 --> <!-- MATCHED MATCHED MATCHED -->.  Other <!-- open: 584, close: 583 --><font class="lisp">*catches</font><!-- open: 584, close: 584 --> <!-- MATCHED MATCHED MATCHED --> are skipped over.
Both <!-- open: 585, close: 584 --><font class="italic">x</font><!-- open: 585, close: 585 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 586, close: 585 --><font class="italic">tag</font><!-- open: 586, close: 586 --> <!-- MATCHED MATCHED MATCHED --> are evaluated, unlike the Maclisp <!-- open: 587, close: 586 --><font class="lisp">throw</font><!-- open: 587, close: 587 --> <!-- MATCHED MATCHED MATCHED --> function.

The values <!-- open: 588, close: 587 --><font class="lisp">t</font><!-- open: 588, close: 588 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 589, close: 588 --><font class="lisp">nil</font><!-- open: 589, close: 589 --> <!-- MATCHED MATCHED MATCHED --> for <!-- open: 590, close: 589 --><font class="italic">tag</font><!-- open: 590, close: 590 --> <!-- MATCHED MATCHED MATCHED --> are reserved.  <!-- open: 591, close: 590 --><font class="lisp">nil</font><!-- open: 591, close: 591 --> <!-- MATCHED MATCHED MATCHED --> may not
be used, because it would cause an ambiguity in the returned values of <!-- open: 592, close: 591 --><font class="lisp">*catch</font><!-- open: 592, close: 592 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 593, close: 592 --><font class="lisp">t</font><!-- open: 593, close: 593 --> <!-- MATCHED MATCHED MATCHED --> invokes a special feature whereby the entire stack is unwound, and then
a coroutine transfer to the invoking stack is done.  During this process
<!-- open: 594, close: 593 --><font class="lisp">unwind-protect</font><!-- open: 594, close: 594 --> <!-- MATCHED MATCHED MATCHED -->s receive control, but <!-- open: 595, close: 594 --><font class="lisp">catch-all</font><!-- open: 595, close: 595 --> <!-- MATCHED MATCHED MATCHED -->s do not.  This feature
is provided for the benefit of system programs which want to completely unwind a stack.
It leaves the stack in a somewhat inconsistent state; it is best to
do a <!-- open: 596, close: 595 --><font class="lisp">stack-preset</font><!-- open: 596, close: 596 --> <!-- MATCHED MATCHED MATCHED --> immediately afterwards.

See the description of <!-- open: 597, close: 596 --><font class="lisp">*catch</font><!-- open: 597, close: 597 --> <!-- MATCHED MATCHED MATCHED --> for further details.
</div>

<div class='defmac' id='catch'><font class='exdent'><font class='funcname' id='catch'>catch</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --></div><div class='defmac id='throw''><font class='exdent'><font class='funcname' id='throw'>throw</font><font class="italic"> Macro</font><br></font><!-- end font_exdent --><!-- open: 598, close: 597 --><font class="lisp">catch</font><!-- open: 598, close: 598 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 599, close: 598 --><font class="lisp">throw</font><!-- open: 599, close: 599 --> <!-- MATCHED MATCHED MATCHED --> are provided only for Maclisp compatibility.
They expand as follows:
<pre class='lisp'>
(catch <!-- open: 600, close: 599 --><font class="italic">form</font><!-- open: 600, close: 600 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 601, close: 600 --><font class="italic">tag</font><!-- open: 601, close: 601 --> <!-- MATCHED MATCHED MATCHED -->) ==&gt; (*catch (quote <!-- open: 602, close: 601 --><font class="italic">tag</font><!-- open: 602, close: 602 --> <!-- MATCHED MATCHED MATCHED -->) <!-- open: 603, close: 602 --><font class="italic">form</font><!-- open: 603, close: 603 --> <!-- MATCHED MATCHED MATCHED -->)
(throw <!-- open: 604, close: 603 --><font class="italic">form</font><!-- open: 604, close: 604 --> <!-- MATCHED MATCHED MATCHED --> <!-- open: 605, close: 604 --><font class="italic">tag</font><!-- open: 605, close: 605 --> <!-- MATCHED MATCHED MATCHED -->) ==&gt; (*throw (quote <!-- open: 606, close: 605 --><font class="italic">tag</font><!-- open: 606, close: 606 --> <!-- MATCHED MATCHED MATCHED -->) <!-- open: 607, close: 606 --><font class="italic">form</font><!-- open: 607, close: 607 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
The forms of <!-- open: 608, close: 607 --><font class="lisp">catch</font><!-- open: 608, close: 608 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 609, close: 608 --><font class="lisp">throw</font><!-- open: 609, close: 609 --> <!-- MATCHED MATCHED MATCHED --> without tags are not supported.
</div>

<p class='cindent'><!-- unwinding a stack -->
<div class='defun' id='*unwind-stack'>
  <font class='exdent'>
    <font class='funcname'>*unwind-stack </font>
    <font class='italic' color='purple'>tag value active-frame-count action</font>
  </font><br>
This is a generalization of <!-- open: 610, close: 609 --><font class="lisp">*throw</font><!-- open: 610, close: 610 --> <!-- MATCHED MATCHED MATCHED --> provided for program-manipulating
programs such as the error handler.

<!-- open: 611, close: 610 --><font class="italic">tag</font><!-- open: 611, close: 611 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 612, close: 611 --><font class="italic">value</font><!-- open: 612, close: 612 --> <!-- MATCHED MATCHED MATCHED --> are the same as the corresponding arguments to
<!-- open: 613, close: 612 --><font class="lisp">*throw</font><!-- open: 613, close: 613 --> <!-- MATCHED MATCHED MATCHED -->.

<!-- open: 614, close: 613 --><font class="italic">active-frame-count</font><!-- open: 614, close: 614 --> <!-- MATCHED MATCHED MATCHED -->, if non-<!-- open: 615, close: 614 --><font class="lisp">nil</font><!-- open: 615, close: 615 --> <!-- MATCHED MATCHED MATCHED -->, is the number of frames
to be unwound.  If this counts down to zero before a suitable <!-- open: 616, close: 615 --><font class="lisp">*catch</font><!-- open: 616, close: 616 --> <!-- MATCHED MATCHED MATCHED -->
is found, the <!-- open: 617, close: 616 --><font class="lisp">*unwind-stack</font><!-- open: 617, close: 617 --> <!-- MATCHED MATCHED MATCHED --> terminates and
<!-- open: 618, close: 617 --><font class="italic">that frame</font><!-- open: 618, close: 618 --> <!-- MATCHED MATCHED MATCHED --> returns <!-- open: 619, close: 618 --><font class="italic">value</font><!-- open: 619, close: 619 --> <!-- MATCHED MATCHED MATCHED --> to whoever called it.
This is similar to Maclisp's <!-- open: 620, close: 619 --><font class="lisp">freturn</font><!-- open: 620, close: 620 --> <!-- MATCHED MATCHED MATCHED --> function.
'findex "freturn"

If <!-- open: 621, close: 620 --><font class="italic">action</font><!-- open: 621, close: 621 --> <!-- MATCHED MATCHED MATCHED --> is non-<!-- open: 622, close: 621 --><font class="lisp">nil</font><!-- open: 622, close: 622 --> <!-- MATCHED MATCHED MATCHED -->, whenever the <!-- open: 623, close: 622 --><font class="lisp">*unwind-stack</font><!-- open: 623, close: 623 --> <!-- MATCHED MATCHED MATCHED --> would be
ready to terminate (either due to <!-- open: 624, close: 623 --><font class="italic">active-frame-count</font><!-- open: 624, close: 624 --> <!-- MATCHED MATCHED MATCHED --> or due to
<!-- open: 625, close: 624 --><font class="italic">tag</font><!-- open: 625, close: 625 --> <!-- MATCHED MATCHED MATCHED --> being caught as in <!-- open: 626, close: 625 --><font class="lisp">*throw</font><!-- open: 626, close: 626 --> <!-- MATCHED MATCHED MATCHED -->), instead, a stack call is
forced to the previous stack, generally the error handler.  The
unwound stack is left in <!-- open: 627, close: 626 --><font class="italic">awaiting-return</font><!-- open: 627, close: 627 --> <!-- MATCHED MATCHED MATCHED --> state, such that the
value returned when the stack is resumed will become the value
returned by the frame, (i.e. the <!-- open: 628, close: 627 --><font class="italic">value</font><!-- open: 628, close: 628 --> <!-- MATCHED MATCHED MATCHED --> argument to
<!-- open: 629, close: 628 --><font class="lisp">*unwind-stack</font><!-- open: 629, close: 629 --> <!-- MATCHED MATCHED MATCHED --> will be ignored in this case, and the value passed to
the stack when it is resumed will be used instead.)

Note that if both <!-- open: 630, close: 629 --><font class="italic">active-frame-count</font><!-- open: 630, close: 630 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 631, close: 630 --><font class="italic">action</font><!-- open: 631, close: 631 --> <!-- MATCHED MATCHED MATCHED --> are <!-- open: 632, close: 631 --><font class="lisp">nil</font><!-- open: 632, close: 632 --> <!-- MATCHED MATCHED MATCHED -->,
<!-- open: 633, close: 632 --><font class="lisp">*unwind-stack</font><!-- open: 633, close: 633 --> <!-- MATCHED MATCHED MATCHED --> is identical to <!-- open: 634, close: 633 --><font class="lisp">*throw</font><!-- open: 634, close: 634 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<p class='cindent'><!-- unwind protection -->
<p class='cindent'><!-- cleanup handlers -->
<div class='defmac' id='unwind-protect'><font class='exdent'><font class='funcname' id='unwind-protect'>unwind-protect</font><font class="italic"> Macro</font></br></font><!-- end font_exdent -->Sometimes it is necessary to evaluate a form and make sure that
certain side-effects take place after the form is evaluated;
a typical example is:
<pre class='lisp'>
(progn
   (turn-on-water-faucet)
   (hairy-function 3 nil 'foo)
   (turn-off-water-faucet))
</pre>
The non-local exit facility of Lisp creates a situation in which
the above code won't work, however: if <!-- open: 635, close: 634 --><font class="lisp">hairy-function</font><!-- open: 635, close: 635 --> <!-- MATCHED MATCHED MATCHED --> should
do a <!-- open: 636, close: 635 --><font class="lisp">*throw</font><!-- open: 636, close: 636 --> <!-- MATCHED MATCHED MATCHED --> to a <!-- open: 637, close: 636 --><font class="lisp">*catch</font><!-- open: 637, close: 637 --> <!-- MATCHED MATCHED MATCHED --> which is outside of the <!-- open: 638, close: 637 --><font class="lisp">progn</font><!-- open: 638, close: 638 --> <!-- MATCHED MATCHED MATCHED -->
form, then <!-- open: 639, close: 638 --><font class="lisp">(turn-off-water-faucet)</font><!-- open: 639, close: 639 --> <!-- MATCHED MATCHED MATCHED --> will never be evaluated
(and the faucet will presumably be left running).

In order to allow the above program to work, it can
be rewritten using <!-- open: 640, close: 639 --><font class="lisp">unwind-protect</font><!-- open: 640, close: 640 --> <!-- MATCHED MATCHED MATCHED --> as follows:
<pre class='lisp'>
(unwind-protect
  (progn (turn-on-water-faucet)
	 (hairy-function 3 nil 'foo))
  (turn-off-water-faucet))
</pre>
If <!-- open: 641, close: 640 --><font class="lisp">hairy-function</font><!-- open: 641, close: 641 --> <!-- MATCHED MATCHED MATCHED --> does a <!-- open: 642, close: 641 --><font class="lisp">*throw</font><!-- open: 642, close: 642 --> <!-- MATCHED MATCHED MATCHED --> which attempts to quit
out of the evaluation of the <!-- open: 643, close: 642 --><font class="lisp">unwind-protect</font><!-- open: 643, close: 643 --> <!-- MATCHED MATCHED MATCHED -->, the
<!-- open: 644, close: 643 --><font class="lisp">(turn-off-water-faucet)</font><!-- open: 644, close: 644 --> <!-- MATCHED MATCHED MATCHED --> form will be evaluated in between
the time of the <!-- open: 645, close: 644 --><font class="lisp">*throw</font><!-- open: 645, close: 645 --> <!-- MATCHED MATCHED MATCHED --> and the time at which the <!-- open: 646, close: 645 --><font class="lisp">*catch</font><!-- open: 646, close: 646 --> <!-- MATCHED MATCHED MATCHED --> returns.
If the <!-- open: 647, close: 646 --><font class="lisp">progn</font><!-- open: 647, close: 647 --> <!-- MATCHED MATCHED MATCHED --> returns normally, then the <!-- open: 648, close: 647 --><font class="lisp">(turn-off-water-faucet)</font><!-- open: 648, close: 648 --> <!-- MATCHED MATCHED MATCHED -->
is evaluated, and the <!-- open: 649, close: 648 --><font class="lisp">unwind-protect</font><!-- open: 649, close: 649 --> <!-- MATCHED MATCHED MATCHED --> returns the result of the <!-- open: 650, close: 649 --><font class="lisp">progn</font><!-- open: 650, close: 650 --> <!-- MATCHED MATCHED MATCHED -->.
One thing to note is that <!-- open: 651, close: 650 --><font class="lisp">unwind-protect</font><!-- open: 651, close: 651 --> <!-- MATCHED MATCHED MATCHED --> cannot return multiple values.

The general form of <!-- open: 652, close: 651 --><font class="lisp">unwind-protect</font><!-- open: 652, close: 652 --> <!-- MATCHED MATCHED MATCHED --> looks like
<pre class='lisp'>
(unwind-protect <!-- open: 653, close: 652 --><font class="italic">protected-form</font><!-- open: 653, close: 653 --> <!-- MATCHED MATCHED MATCHED -->
                <!-- open: 654, close: 653 --><font class="italic">form1</font><!-- open: 654, close: 654 --> <!-- MATCHED MATCHED MATCHED -->
                <!-- open: 655, close: 654 --><font class="italic">form2</font><!-- open: 655, close: 655 --> <!-- MATCHED MATCHED MATCHED -->
                ...)
</pre>
<!-- open: 656, close: 655 --><font class="italic">protected-form</font><!-- open: 656, close: 656 --> <!-- MATCHED MATCHED MATCHED --> is evaluated, and when it returns or when it
attempts to quit out of the <!-- open: 657, close: 656 --><font class="lisp">unwind-protect</font><!-- open: 657, close: 657 --> <!-- MATCHED MATCHED MATCHED -->, the <!-- open: 658, close: 657 --><font class="italic">form</font><!-- open: 658, close: 658 --> <!-- MATCHED MATCHED MATCHED -->s
are evaluated.
</div>

<div class='defmac' id='let-globally'><font class='exdent'><font class='funcname' id='let-globally'>let-globally</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --><!-- open: 659, close: 658 --><font class="lisp">let-globally</font><!-- open: 659, close: 659 --> <!-- MATCHED MATCHED MATCHED --> is similar in form to <!-- open: 660, close: 659 --><font class="lisp">let</font><!-- open: 660, close: 660 --> <!-- MATCHED MATCHED MATCHED --> (see <font color='red'>LINK:(</font>let-fun)).
The difference is that <!-- open: 661, close: 660 --><font class="lisp">let-globally</font><!-- open: 661, close: 661 --> <!-- MATCHED MATCHED MATCHED --> does not <!-- open: 662, close: 661 --><font class="italic">bind</font><!-- open: 662, close: 662 --> <!-- MATCHED MATCHED MATCHED --> the
variables; instead, it <!-- open: 663, close: 662 --><font class="italic">sets</font><!-- open: 663, close: 663 --> <!-- MATCHED MATCHED MATCHED --> them, and sets up an <!-- open: 664, close: 663 --><font class="lisp">unwind-protect</font><!-- open: 664, close: 664 --> <!-- MATCHED MATCHED MATCHED -->
(see <font color='red'>LINK:(</font>unwind-protect-fun)) to set them back.  The important
difference between <!-- open: 665, close: 664 --><font class="lisp">let-globally</font><!-- open: 665, close: 665 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 666, close: 665 --><font class="lisp">let</font><!-- open: 666, close: 666 --> <!-- MATCHED MATCHED MATCHED --> is that when
the current stack (see <a href='fd_sg.html#stack-group'>this link</a>) cocalls some other stack
group, the old values of the variables are <!-- open: 667, close: 666 --><font class="italic">not</font><!-- open: 667, close: 667 --> <!-- MATCHED MATCHED MATCHED --> restored.
</div>

<div class='defmac' id='catch-all'><font class='exdent'><font class='funcname' id='catch-all'>catch-all</font><font class="italic"> Macro</font></br></font><!-- end font_exdent --><!-- open: 668, close: 667 --><font class="lisp">(catch-all <!-- open: 669, close: 667 --><font class="italic">form</font><!-- open: 669, close: 668 -->)</font><!-- open: 669, close: 669 --> <!-- MATCHED MATCHED MATCHED --> is like <!-- open: 670, close: 669 --><font class="lisp">(*catch <!-- open: 671, close: 669 --><font class="italic">some-tag form</font><!-- open: 671, close: 670 -->)</font><!-- open: 671, close: 671 --> <!-- MATCHED MATCHED MATCHED -->
except that it will catch a
<!-- open: 672, close: 671 --><font class="lisp">*throw</font><!-- open: 672, close: 672 --> <!-- MATCHED MATCHED MATCHED --> to any tag at all.  Since the tag thrown to
is the second returned value, the caller of <!-- open: 673, close: 672 --><font class="lisp">catch-all</font><!-- open: 673, close: 673 --> <!-- MATCHED MATCHED MATCHED --> may continue 
throwing to that tag if he wants.  The one thing that <!-- open: 674, close: 673 --><font class="lisp">catch-all</font><!-- open: 674, close: 674 --> <!-- MATCHED MATCHED MATCHED -->
will not catch is a <!-- open: 675, close: 674 --><font class="lisp">*throw</font><!-- open: 675, close: 675 --> <!-- MATCHED MATCHED MATCHED --> to <!-- open: 676, close: 675 --><font class="lisp">t</font><!-- open: 676, close: 676 --> <!-- MATCHED MATCHED MATCHED -->.
<!-- open: 677, close: 676 --><font class="lisp">catch-all</font><!-- open: 677, close: 677 --> <!-- MATCHED MATCHED MATCHED --> is a macro which expands into <!-- open: 678, close: 677 --><font class="lisp">*catch</font><!-- open: 678, close: 678 --> <!-- MATCHED MATCHED MATCHED --> with a <!-- open: 679, close: 678 --><font class="italic">tag</font><!-- open: 679, close: 679 --> <!-- MATCHED MATCHED MATCHED --> of <!-- open: 680, close: 679 --><font class="lisp">nil</font><!-- open: 680, close: 680 --> <!-- MATCHED MATCHED MATCHED -->.
</div>

<div class='section' id='6.4'>6.4 Mapping</div><p class='cindent'><!-- "mapping" -->

<div class='defun' id='map'>
  <font class='exdent'>
    <font class='funcname'>map </font>
    <font class='italic' color='purple'>fcn &rest lists</font>
  </font><br>
</div><div class='defun1' id='mapc'>
<font class='exdent'><font class='funcname'>mapc </font><font class='italic' color='purple'>fcn &rest lists
</font></font><br></div><div class='defun1' id='maplist'>
<font class='exdent'><font class='funcname'>maplist </font><font class='italic' color='purple'>fcn &rest lists
</font></font><br></div><div class='defun1' id='mapcar'>
<font class='exdent'><font class='funcname'>mapcar </font><font class='italic' color='purple'>fcn &rest lists
</font></font><br></div><div class='defun1' id='mapcon'>
<font class='exdent'><font class='funcname'>mapcon </font><font class='italic' color='purple'>fcn &rest lists
</font></font><br></div><div class='defun1' id='mapcan'>
<font class='exdent'><font class='funcname'>mapcan </font><font class='italic' color='purple'>fcn &rest lists
</font></font><br>
Mapping is a type of iteration in which a function is 
successively applied to pieces of a list.
There are several options for the way in which the pieces of the list are
chosen and for what is done with the results returned by the applications of
the function.

For example, <!-- open: 681, close: 680 --><font class="lisp">mapcar</font><!-- open: 681, close: 681 --> <!-- MATCHED MATCHED MATCHED --> operates on successive <!-- open: 682, close: 681 --><font class="italic">elements</font><!-- open: 682, close: 682 --> <!-- MATCHED MATCHED MATCHED --> of the list. 
As it goes down the list, it calls the function giving it an element
of the list as its one argument:  first the <!-- open: 683, close: 682 --><font class="lisp">car</font><!-- open: 683, close: 683 --> <!-- MATCHED MATCHED MATCHED -->, then the
<!-- open: 684, close: 683 --><font class="lisp">cadr</font><!-- open: 684, close: 684 --> <!-- MATCHED MATCHED MATCHED -->, then the <!-- open: 685, close: 684 --><font class="lisp">caddr</font><!-- open: 685, close: 685 --> <!-- MATCHED MATCHED MATCHED -->, etc., continuing until the end of the
list is reached.  The value returned by <!-- open: 686, close: 685 --><font class="lisp">mapcar</font><!-- open: 686, close: 686 --> <!-- MATCHED MATCHED MATCHED --> is a list of the
results of the successive calls to the function.  An example of the
use of <!-- open: 687, close: 686 --><font class="lisp">mapcar</font><!-- open: 687, close: 687 --> <!-- MATCHED MATCHED MATCHED --> would be <!-- open: 688, close: 687 --><font class="lisp">mapcar</font><!-- open: 688, close: 688 --> <!-- MATCHED MATCHED MATCHED -->'ing the function <!-- open: 689, close: 688 --><font class="lisp">abs</font><!-- open: 689, close: 689 --> <!-- MATCHED MATCHED MATCHED --> over
the list <!-- open: 690, close: 689 --><font class="lisp">(1 -2 -4.5 6.0e15 -4.2)</font><!-- open: 690, close: 690 --> <!-- MATCHED MATCHED MATCHED -->, which would be written as
<!-- open: 691, close: 690 --><font class="lisp">(mapcar (function abs) '(1 -2 -4.5 6.0e15 -4.2))</font><!-- open: 691, close: 691 --> <!-- MATCHED MATCHED MATCHED -->.
The result is <!-- open: 692, close: 691 --><font class="lisp">(1 2 4.5 6.0e15
4.2)</font><!-- open: 692, close: 692 --> <!-- MATCHED MATCHED MATCHED -->.  

In general, the mapping functions take any number of arguments.  For example,
<pre class='lisp'>
(mapcar <!-- open: 693, close: 692 --><font class="italic">f x1 x2 ... xn</font><!-- open: 693, close: 693 --> <!-- MATCHED MATCHED MATCHED -->)
</pre>
In this case <!-- open: 694, close: 693 --><font class="italic">f</font><!-- open: 694, close: 694 --> <!-- MATCHED MATCHED MATCHED --> must be a function of <!-- open: 695, close: 694 --><font class="italic">n</font><!-- open: 695, close: 695 --> <!-- MATCHED MATCHED MATCHED --> arguments.
<!-- open: 696, close: 695 --><font class="lisp">mapcar</font><!-- open: 696, close: 696 --> <!-- MATCHED MATCHED MATCHED --> will proceed
down the lists <!-- open: 697, close: 696 --><font class="italic">x1, x2, ..., xn</font><!-- open: 697, close: 697 --> <!-- MATCHED MATCHED MATCHED --> in parallel.
The first argument to <!-- open: 698, close: 697 --><font class="italic">f</font><!-- open: 698, close: 698 --> <!-- MATCHED MATCHED MATCHED --> will
come from <!-- open: 699, close: 698 --><font class="italic">x1</font><!-- open: 699, close: 699 --> <!-- MATCHED MATCHED MATCHED -->, the second from <!-- open: 700, close: 699 --><font class="italic">x2</font><!-- open: 700, close: 700 --> <!-- MATCHED MATCHED MATCHED -->, etc.
The iteration stops as soon as
any of the lists is exhausted.

There are five other mapping functions besides <!-- open: 701, close: 700 --><font class="lisp">mapcar</font><!-- open: 701, close: 701 --> <!-- MATCHED MATCHED MATCHED -->.  <!-- open: 702, close: 701 --><font class="lisp">maplist</font><!-- open: 702, close: 702 --> <!-- MATCHED MATCHED MATCHED -->
is like <!-- open: 703, close: 702 --><font class="lisp">mapcar</font><!-- open: 703, close: 703 --> <!-- MATCHED MATCHED MATCHED --> except that the function is applied to the list and
successive cdr's of that list rather than to successive elements of the
list.  <!-- open: 704, close: 703 --><font class="lisp">map</font><!-- open: 704, close: 704 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 705, close: 704 --><font class="lisp">mapc</font><!-- open: 705, close: 705 --> <!-- MATCHED MATCHED MATCHED --> are like <!-- open: 706, close: 705 --><font class="lisp">maplist</font><!-- open: 706, close: 706 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 707, close: 706 --><font class="lisp">mapcar</font><!-- open: 707, close: 707 --> <!-- MATCHED MATCHED MATCHED -->
respectively, except that they don't return any useful value.  These
functions are used when the function is being called merely for its
side-effects, rather than its returned values.  <!-- open: 708, close: 707 --><font class="lisp">mapcan</font><!-- open: 708, close: 708 --> <!-- MATCHED MATCHED MATCHED --> and
<!-- open: 709, close: 708 --><font class="lisp">mapcon</font><!-- open: 709, close: 709 --> <!-- MATCHED MATCHED MATCHED --> are like <!-- open: 710, close: 709 --><font class="lisp">mapcar</font><!-- open: 710, close: 710 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 711, close: 710 --><font class="lisp">maplist</font><!-- open: 711, close: 711 --> <!-- MATCHED MATCHED MATCHED --> respectively, except
that they combine the results of the function using <!-- open: 712, close: 711 --><font class="lisp">nconc</font><!-- open: 712, close: 712 --> <!-- MATCHED MATCHED MATCHED --> instead
of <!-- open: 713, close: 712 --><font class="lisp">list</font><!-- open: 713, close: 713 --> <!-- MATCHED MATCHED MATCHED -->.  That is,
<pre class='lisp'>
(defun mapcon (f x y)
    (apply 'nconc (maplist f x y)))
</pre>
Of course, this definition is less general than the real one.

Sometimes a <!-- open: 714, close: 713 --><font class="lisp">do</font><!-- open: 714, close: 714 --> <!-- MATCHED MATCHED MATCHED --> or a straightforward recursion is preferable to a
map;  however, the mapping functions should be used wherever they
naturally apply because this increases the clarity of the code. 

Often <!-- open: 715, close: 714 --><font class="italic">f</font><!-- open: 715, close: 715 --> <!-- MATCHED MATCHED MATCHED --> will be a lambda-expression, rather than a symbol;
for example,
<pre class='lisp'>
(mapcar (function (lambda (x) (cons x something)))
	some-list)
</pre>

The functional argument to a mapping function must be acceptable
to <!-- open: 716, close: 715 --><font class="lisp">apply</font><!-- open: 716, close: 716 --> <!-- MATCHED MATCHED MATCHED --> - it cannot be a macro or the name of a special form.
Of course, there is nothing wrong with using functions which have optional
and rest parameters.


Here is a table showing the relations between
the six map functions.
<pre>
<!-- open: 717, close: 716 --><font class="lispcode">
                              applies function to

                         |  successive  |   successive  |
                         |   sublists   |    elements   |
          ---------------+--------------+---------------+
              its own    |              |               | 
              second     |     map      |     mapc      |
             argument    |              |               |
          ---------------+--------------+---------------+
            list of the  |              |               |
returns      function    |    maplist   |    mapcar     |
              results    |              |               |
          ---------------+--------------+---------------+
            nconc of the |              |               |
              function   |    mapcon    |    mapcan     |
              results    |              |               |
          ---------------+--------------+---------------+</font><!-- open: 717, close: 717 --> <!-- MATCHED MATCHED MATCHED -->
</pre>
	There are also functions (<!-- open: 718, close: 717 --><font class="lisp">mapatoms</font><!-- open: 718, close: 718 --> <!-- MATCHED MATCHED MATCHED --> and <!-- open: 719, close: 718 --><font class="lisp">mapatoms-all</font><!-- open: 719, close: 719 --> <!-- MATCHED MATCHED MATCHED -->)
for mapping over all symbols in certain
packages.  See the explanation of packages (<font color='red'>LINK:(</font>package)).

</div>
<!-- eof -->
</body>
</html>

